@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,297 @@
1
+ /**
2
+ * Breadcrumbs: where you are, and every step back to the top.
3
+ *
4
+ * A `<nav>` with a name, holding an ordered list of links. Three details are
5
+ * what separate it from a row of links:
6
+ *
7
+ * - **The current page is still a LINK, marked `aria-current="page"`.** That
8
+ * is what the authoring practices have, and the alternative is worse: an
9
+ * `<a>` with no `href` has no role at all, so it is announced as text while
10
+ * looking like something to press.
11
+ * - **The separator is not content.** A "/" between the items belongs to the
12
+ * stylesheet, or to an element marked `aria-hidden`; announced, it is read
13
+ * as "slash" between every pair.
14
+ * - **The list is ordered.** `<ol>` says the sequence matters, which is the
15
+ * whole point of a trail.
16
+ */
17
+
18
+ import {
19
+ cells,
20
+ type Child,
21
+ For,
22
+ createContext,
23
+ getContext,
24
+ getOwner,
25
+ type Incoming,
26
+ install,
27
+ } from "@barqjs/core";
28
+ import { ref as makeRef, mergeRefs, type RefTarget } from "@barqjs/primitives/refs";
29
+ import type { ItemAccessors, Key, Node } from "./collections.ts";
30
+ import { buildCollection, type ListCollection } from "./collections.ts";
31
+ import { focusRing } from "./focus.ts";
32
+ import { hover } from "./interactions/hover.ts";
33
+ import type { ElementRef, PressEvent } from "./interactions/press.ts";
34
+ import { link, type LinkOptions } from "./link.tsx";
35
+ import {
36
+ access,
37
+ type DOMProps,
38
+ filterDOMProps,
39
+ fromProps,
40
+ type MaybeAccessor,
41
+ mergeProps,
42
+ type StyleProps,
43
+ styleProps,
44
+ } from "./utils.ts";
45
+
46
+ // ---------------------------------------------------------------------------
47
+ // Hooks
48
+ // ---------------------------------------------------------------------------
49
+
50
+ export interface BreadcrumbsOptions {
51
+ "aria-label"?: MaybeAccessor<string | undefined>;
52
+ "aria-labelledby"?: MaybeAccessor<string | undefined>;
53
+ }
54
+
55
+ export interface BreadcrumbsResult {
56
+ navProps: DOMProps;
57
+ }
58
+
59
+ export function breadcrumbs(options: BreadcrumbsOptions = {}): BreadcrumbsResult {
60
+ return {
61
+ navProps: mergeProps(filterDOMProps(options, { labelable: true }), {
62
+ // Named, because a page with more than one landmark of a kind needs
63
+ // telling apart, and "Breadcrumbs" is what a user of one calls it.
64
+ "aria-label": () => access(options["aria-label"]) ?? "Breadcrumbs",
65
+ }),
66
+ };
67
+ }
68
+
69
+ export interface BreadcrumbItemOptions extends Omit<LinkOptions, "elementType"> {
70
+ /** Where you are now. Still a link, and says so with `aria-current`. */
71
+ isCurrent?: MaybeAccessor<boolean | undefined>;
72
+ /** What kind of current. @default "page" */
73
+ "aria-current"?: MaybeAccessor<
74
+ "page" | "step" | "location" | "date" | "time" | boolean | undefined
75
+ >;
76
+ /** @default "a" */
77
+ elementType?: MaybeAccessor<string | undefined>;
78
+ }
79
+
80
+ export interface BreadcrumbItemResult {
81
+ itemProps: DOMProps;
82
+ isPressed: ReturnType<typeof link>["isPressed"];
83
+ }
84
+
85
+ export function breadcrumbItem(
86
+ options: BreadcrumbItemOptions,
87
+ ref?: ElementRef,
88
+ ): BreadcrumbItemResult {
89
+ const isCurrent = (): boolean => access(options.isCurrent) === true;
90
+ const elementType = (): string => access(options.elementType) ?? "a";
91
+ const isHeading = (): boolean => /^h[1-6]$/.test(elementType());
92
+
93
+ const { linkProps, isPressed } = link({ ...options, elementType }, ref);
94
+
95
+ return {
96
+ isPressed,
97
+ itemProps: mergeProps(
98
+ // A heading is not a link at all, so it takes none of the link's
99
+ // behaviour: `<h1>Current page</h1>` is a perfectly good last crumb.
100
+ isHeading() ? {} : linkProps,
101
+ {
102
+ "aria-disabled": () => access(options.isDisabled) === true || undefined,
103
+ // The current crumb stays a LINK, as the authoring practices have it:
104
+ // `aria-current="page"` is what says you are already there, and a link
105
+ // with no `href` has no role at all — it is a span that looks like one.
106
+ "aria-current": () =>
107
+ isCurrent() ? (access(options["aria-current"]) ?? "page") : undefined,
108
+ },
109
+ ),
110
+ };
111
+ }
112
+
113
+ // ---------------------------------------------------------------------------
114
+ // Components
115
+ // ---------------------------------------------------------------------------
116
+
117
+ interface BreadcrumbsContextValue {
118
+ isDisabled: () => boolean;
119
+ onAction: () => ((key: Key) => void) | undefined;
120
+ }
121
+
122
+ const BreadcrumbsContext = createContext<BreadcrumbsContextValue | null>(null);
123
+ const CrumbNodeContext = createContext<{ node: Node<unknown>; isLast: boolean } | null>(null);
124
+
125
+ export function useBreadcrumbs(): BreadcrumbsContextValue {
126
+ const value = getContext(BreadcrumbsContext);
127
+ if (value === null || value === undefined) {
128
+ throw new Error("A Breadcrumb must be rendered inside Breadcrumbs.");
129
+ }
130
+ return value;
131
+ }
132
+
133
+ /** The collection node the crumb being built is for, and whether it is last. */
134
+ export function useCrumb(): { node: Node<unknown>; isLast: boolean } {
135
+ const value = getContext(CrumbNodeContext);
136
+ if (value === null || value === undefined) {
137
+ throw new Error("A Breadcrumb must be rendered inside Breadcrumbs' item callback.");
138
+ }
139
+ return value;
140
+ }
141
+
142
+ export interface BreadcrumbsComponentProps<T> extends StyleProps, ItemAccessors<T> {
143
+ /** The trail, from the top down. The last one is where you are. */
144
+ items: Iterable<T>;
145
+ /** How one crumb renders. Return a `<Breadcrumb>`. */
146
+ children: (item: T) => Child;
147
+ isDisabled?: boolean;
148
+ "aria-label"?: string;
149
+ "aria-labelledby"?: string;
150
+ ref?: RefTarget<HTMLElement>;
151
+ onAction?: (key: Key) => void;
152
+ }
153
+
154
+ /**
155
+ * ```tsx
156
+ * <Breadcrumbs items={trail()} onAction={(key) => go(key)}>
157
+ * {(crumb) => <Breadcrumb>{crumb.name}</Breadcrumb>}
158
+ * </Breadcrumbs>
159
+ * ```
160
+ */
161
+ export function Breadcrumbs<T>(props: BreadcrumbsComponentProps<T>) {
162
+ const options = fromProps(cells(props) as unknown as Incoming<Record<string, unknown>>);
163
+ const { navProps } = breadcrumbs(options);
164
+
165
+ const collection = (): ListCollection<T> =>
166
+ buildCollection(props.items, cells(props) as unknown as ItemAccessors<T>);
167
+
168
+ const owner = getOwner();
169
+ if (owner !== null) {
170
+ install(owner, BreadcrumbsContext, () => ({
171
+ isDisabled: () => props.isDisabled === true,
172
+ onAction: () => props.onAction,
173
+ }));
174
+ }
175
+
176
+ const elementProps = mergeProps(
177
+ navProps,
178
+ filterDOMProps(fromProps(cells(props)), { global: true }),
179
+ styleProps(cells(props)),
180
+ {
181
+ "data-testid": () => props["data-testid"],
182
+ },
183
+ );
184
+
185
+ const render = props.children;
186
+
187
+ return (
188
+ <nav {...elementProps} ref={mergeRefs(props.ref)}>
189
+ <ol>
190
+ <For each={() => [...collection()]}>
191
+ {(node: Node<T>) => {
192
+ const rowOwner = getOwner();
193
+ if (rowOwner !== null) {
194
+ install(rowOwner, CrumbNodeContext, () => ({
195
+ node: node as Node<unknown>,
196
+ isLast: node.nextKey === undefined,
197
+ }));
198
+ }
199
+ return render(node.value as T);
200
+ }}
201
+ </For>
202
+ </ol>
203
+ </nav>
204
+ );
205
+ }
206
+
207
+ export interface BreadcrumbComponentProps extends StyleProps {
208
+ children?: Child;
209
+ href?: string;
210
+ target?: string;
211
+ rel?: string;
212
+ isDisabled?: boolean;
213
+ /** Override which crumb is the current one. @default the last */
214
+ isCurrent?: boolean;
215
+ ref?: RefTarget<HTMLAnchorElement>;
216
+ onPress?: (event: PressEvent) => void;
217
+ }
218
+
219
+ /**
220
+ * One crumb.
221
+ *
222
+ * The last is the current page, marked `aria-current="page"`. A crumb with no
223
+ * `href` renders as a `<span>`: an anchor without one is not a link, and
224
+ * dressing it as one is a promise the markup does not keep.
225
+ */
226
+ export function Breadcrumb(props: BreadcrumbComponentProps) {
227
+ const domRef = makeRef<HTMLAnchorElement>();
228
+ const trail = useBreadcrumbs();
229
+ const { node, isLast } = useCrumb();
230
+
231
+ const isCurrent = (): boolean => props.isCurrent ?? isLast;
232
+ const href = (): string | undefined => props.href ?? (node.props?.href as string | undefined);
233
+
234
+ const isDisabled = (): boolean => props.isDisabled === true || trail.isDisabled();
235
+
236
+ /**
237
+ * Whether this crumb is a link at all.
238
+ *
239
+ * A disabled one is not: `link` takes the `href` off it, and an `<a>` with
240
+ * no `href` has no role — so it would be announced as text while still
241
+ * looking like something to press.
242
+ */
243
+ const isLink = (): boolean => href() !== undefined && !isDisabled();
244
+
245
+ const { itemProps, isPressed } = breadcrumbItem(
246
+ {
247
+ isCurrent,
248
+ isDisabled,
249
+ href,
250
+ target: () => props.target,
251
+ rel: () => props.rel,
252
+ onPress: (event) => {
253
+ props.onPress?.(event);
254
+ trail.onAction()?.(node.key);
255
+ },
256
+ },
257
+ domRef,
258
+ );
259
+
260
+ const { hoverProps, isHovered } = hover({ isDisabled });
261
+ const { focusProps, isFocusVisible } = focusRing();
262
+
263
+ const elementProps = mergeProps(
264
+ itemProps,
265
+ hoverProps,
266
+ focusProps,
267
+ filterDOMProps(fromProps(cells(props)), { global: true }),
268
+ styleProps(cells(props)),
269
+ {
270
+ "data-current": isCurrent,
271
+ "data-pressed": isPressed,
272
+ "data-hovered": isHovered,
273
+ "data-focus-visible": isFocusVisible,
274
+ "data-disabled": isDisabled,
275
+ "data-testid": () => props["data-testid"],
276
+ },
277
+ );
278
+
279
+ return (
280
+ <li>
281
+ {() =>
282
+ !isLink() ? (
283
+ <span
284
+ {...elementProps}
285
+ ref={mergeRefs(domRef.set as unknown as RefTarget<HTMLSpanElement>)}
286
+ >
287
+ {props.children}
288
+ </span>
289
+ ) : (
290
+ <a {...elementProps} ref={mergeRefs(domRef.set, props.ref)}>
291
+ {props.children}
292
+ </a>
293
+ )
294
+ }
295
+ </li>
296
+ );
297
+ }