@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,721 @@
1
+ /**
2
+ * A listbox: a set of options, one Tab stop, arrow keys inside.
3
+ *
4
+ * Everything that makes it a listbox rather than a styled list is in
5
+ * `selection.ts`; what is here is the roles and the relationships. Two are
6
+ * easy to get wrong:
7
+ *
8
+ * - The options must be the listbox's OWN children in the accessibility tree.
9
+ * A wrapper `<div>` between them without `role="presentation"` breaks the
10
+ * parent/child relationship, and a screen reader stops reporting "2 of 7".
11
+ * - A section is a `role="group"` with `aria-labelledby` pointing at its own
12
+ * heading; the heading itself must not be an option, or it becomes a
13
+ * selectable item that does nothing.
14
+ */
15
+
16
+ import {
17
+ type Accessor,
18
+ type Child,
19
+ createSignal,
20
+ For,
21
+ getOwner,
22
+ type Incoming,
23
+ install,
24
+ onCleanup,
25
+ } from "@barqjs/core";
26
+ import { createContext, getContext, provide } from "@barqjs/core";
27
+ import { ref as makeRef, mergeRefs, type RefTarget } from "@barqjs/primitives/refs";
28
+ import type {
29
+ ItemAccessors,
30
+ Key,
31
+ LayoutDelegate,
32
+ ListStateOptions,
33
+ Node,
34
+ SelectionMode,
35
+ } from "./collections.ts";
36
+ import { listState, type ListState } from "./collections.ts";
37
+ import { focusRing } from "./focus.ts";
38
+ import { hover } from "./interactions/hover.ts";
39
+ import type { ElementRef } from "./interactions/press.ts";
40
+ import { field, type FieldOptions } from "./label.ts";
41
+ import { selectableItem, selectableList, type LinkBehavior } from "./selection.ts";
42
+ import {
43
+ provideStaticSection,
44
+ staticAccessors,
45
+ staticCollection,
46
+ staticItem,
47
+ type StaticCollection,
48
+ } from "./static-collection.ts";
49
+ import {
50
+ contentStyle,
51
+ measureRow,
52
+ rowStyle,
53
+ useVirtualizer,
54
+ type LayoutInfo,
55
+ } from "./virtualizer.tsx";
56
+ import {
57
+ access,
58
+ type DOMProps,
59
+ filterDOMProps,
60
+ fromProps,
61
+ id,
62
+ type MaybeAccessor,
63
+ mergeProps,
64
+ type StyleProps,
65
+ styleProps,
66
+ } from "./utils.ts";
67
+
68
+ export interface ListBoxOptions extends FieldOptions {
69
+ ref: ElementRef;
70
+ /** @default false */
71
+ shouldFocusWrap?: MaybeAccessor<boolean | undefined>;
72
+ /** @default "vertical" */
73
+ orientation?: MaybeAccessor<"horizontal" | "vertical" | undefined>;
74
+ autoFocus?: MaybeAccessor<boolean | "first" | "last" | undefined>;
75
+ /** Track focus with `aria-activedescendant`, for a combobox. */
76
+ shouldUseVirtualFocus?: MaybeAccessor<boolean | undefined>;
77
+ /** Select on pointer up. A menu-like listbox wants this. */
78
+ shouldSelectOnPressUp?: MaybeAccessor<boolean | undefined>;
79
+ disallowEmptySelection?: MaybeAccessor<boolean | undefined>;
80
+ disallowTypeAhead?: MaybeAccessor<boolean | undefined>;
81
+ linkBehavior?: MaybeAccessor<LinkBehavior | undefined>;
82
+ isDisabled?: MaybeAccessor<boolean | undefined>;
83
+ /** Only a WINDOW of the collection is rendered. See `virtualizer.tsx`. */
84
+ isVirtualized?: MaybeAccessor<boolean | undefined>;
85
+ /** Where the rows are, when the DOM cannot answer because they are not in it. */
86
+ layoutDelegate?: LayoutDelegate;
87
+ /** Where the option ids come from. Shared with whatever names one. */
88
+ baseId?: MaybeAccessor<string | undefined>;
89
+ }
90
+
91
+ export interface ListBoxResult {
92
+ listBoxProps: DOMProps;
93
+ labelProps: DOMProps;
94
+ descriptionProps: DOMProps;
95
+ errorMessageProps: DOMProps;
96
+ /** The base every option id in this listbox is derived from. */
97
+ baseId: Accessor<string>;
98
+ }
99
+
100
+ export function listBox(options: ListBoxOptions, state: ListState<unknown>): ListBoxResult {
101
+ const baseId = id(options.baseId);
102
+ const { labelProps, fieldProps, descriptionProps, errorMessageProps } = field({
103
+ ...options,
104
+ // A listbox is not a labelable element.
105
+ labelElementType: "span",
106
+ });
107
+
108
+ const { listProps } = selectableList({
109
+ ...options,
110
+ selectionManager: state.selectionManager,
111
+ collection: state.collection,
112
+ disabledKeys: state.disabledKeys,
113
+ });
114
+
115
+ return {
116
+ baseId,
117
+ labelProps,
118
+ descriptionProps,
119
+ errorMessageProps,
120
+ listBoxProps: mergeProps(filterDOMProps(options, { labelable: true }), listProps, fieldProps, {
121
+ role: "listbox",
122
+ "aria-multiselectable": () =>
123
+ state.selectionManager().selectionMode === "multiple" ? true : undefined,
124
+ "aria-disabled": () => access(options.isDisabled) === true || undefined,
125
+ "aria-orientation": () =>
126
+ access(options.orientation) === "horizontal" ? "horizontal" : undefined,
127
+ // Under virtual focus the listbox never has DOM focus, so the item that
128
+ // does is named here instead.
129
+ "aria-activedescendant": () => {
130
+ if (access(options.shouldUseVirtualFocus) !== true) return undefined;
131
+ const focused = state.selectionManager().focusedKey;
132
+ return focused === null ? undefined : optionIdFor(baseId(), focused);
133
+ },
134
+ }),
135
+ };
136
+ }
137
+
138
+ /**
139
+ * The id an option renders under.
140
+ *
141
+ * `aria-activedescendant` — on the listbox, or on a combobox's input — has to
142
+ * name the option before it exists, so the id is DERIVED from the key rather
143
+ * than generated per element. It is derived from the listbox's own id as well,
144
+ * because two listboxes on one page offering the same key would otherwise
145
+ * write the same id twice.
146
+ */
147
+ export function optionIdFor(baseId: string, key: Key): string {
148
+ return `${baseId}-option-${idFragment(key)}`;
149
+ }
150
+
151
+ /**
152
+ * A key as part of an id.
153
+ *
154
+ * A key is whatever the caller's data uses, and "New York" is a reasonable one;
155
+ * an id holding a space is read by `aria-activedescendant` and
156
+ * `aria-labelledby` as two ids, neither of which exists. Letters, digits and
157
+ * hyphens pass through, so an ordinary key reads the same in the markup, and
158
+ * everything else is written as its code point so that no two keys collide.
159
+ */
160
+ export function idFragment(key: Key): string {
161
+ return String(key).replace(
162
+ /[^A-Za-z0-9-]/g,
163
+ (character) => `_${(character.codePointAt(0) ?? 0).toString(36)}_`,
164
+ );
165
+ }
166
+
167
+ export interface OptionOptions {
168
+ key: Key;
169
+ ref: ElementRef;
170
+ /** The listbox's own id, which the option's is derived from. */
171
+ baseId: MaybeAccessor<string>;
172
+ isDisabled?: MaybeAccessor<boolean | undefined>;
173
+ shouldSelectOnPressUp?: MaybeAccessor<boolean | undefined>;
174
+ shouldUseVirtualFocus?: MaybeAccessor<boolean | undefined>;
175
+ isVirtualized?: MaybeAccessor<boolean | undefined>;
176
+ "aria-label"?: MaybeAccessor<string | undefined>;
177
+ onAction?: () => void;
178
+ /** Whether `onAction` does anything. @default `onAction !== undefined` */
179
+ hasAction?: MaybeAccessor<boolean | undefined>;
180
+ }
181
+
182
+ export interface OptionResult {
183
+ optionProps: DOMProps;
184
+ labelProps: DOMProps;
185
+ descriptionProps: DOMProps;
186
+ isSelected: Accessor<boolean>;
187
+ isFocused: Accessor<boolean>;
188
+ isPressed: Accessor<boolean>;
189
+ isDisabled: Accessor<boolean>;
190
+ allowsSelection: Accessor<boolean>;
191
+ }
192
+
193
+ export function option(options: OptionOptions, state: ListState<unknown>): OptionResult {
194
+ const labelId = id();
195
+ const descriptionId = id();
196
+
197
+ const item = selectableItem({
198
+ ...options,
199
+ id: () => optionIdFor(access(options.baseId), options.key),
200
+ selectionManager: state.selectionManager,
201
+ });
202
+
203
+ const node = (): Node<unknown> | null => state.collection().getItem(options.key);
204
+
205
+ return {
206
+ isSelected: item.isSelected,
207
+ isFocused: item.isFocused,
208
+ isPressed: item.isPressed,
209
+ isDisabled: item.isDisabled,
210
+ allowsSelection: item.allowsSelection,
211
+ labelProps: { id: labelId },
212
+ descriptionProps: { id: descriptionId },
213
+ optionProps: mergeProps(item.itemProps, {
214
+ role: "option",
215
+ // `aria-selected` only where selection is possible: on a listbox that
216
+ // only performs actions, the attribute would say every item is
217
+ // unselected rather than that selection is not the point.
218
+ "aria-selected": () =>
219
+ state.selectionManager().selectionMode !== "none" ? item.isSelected() : undefined,
220
+ "aria-disabled": () => item.isDisabled() || undefined,
221
+ "aria-label": () => access(options["aria-label"]) ?? node()?.["aria-label"],
222
+ // A virtualised list renders a window, so the position has to be stated.
223
+ "aria-posinset": () =>
224
+ access(options.isVirtualized) === true ? (node()?.index ?? 0) + 1 : undefined,
225
+ "aria-setsize": () =>
226
+ access(options.isVirtualized) === true ? state.collection().size : undefined,
227
+ }),
228
+ };
229
+ }
230
+
231
+ export interface ListBoxSectionOptions {
232
+ heading?: MaybeAccessor<unknown>;
233
+ "aria-label"?: MaybeAccessor<string | undefined>;
234
+ }
235
+
236
+ export function listBoxSection(options: ListBoxSectionOptions): {
237
+ itemProps: DOMProps;
238
+ headingProps: DOMProps;
239
+ groupProps: DOMProps;
240
+ } {
241
+ const headingId = id();
242
+ const hasHeading = (): boolean => {
243
+ const heading = access(options.heading);
244
+ return heading !== undefined && heading !== null && heading !== "";
245
+ };
246
+
247
+ return {
248
+ // The `<li>` wrapping the section is not itself an option.
249
+ itemProps: { role: "presentation" },
250
+ headingProps: {
251
+ id: () => (hasHeading() ? headingId() : undefined),
252
+ // The heading is not a child of the group; it names it.
253
+ "aria-hidden": true,
254
+ },
255
+ groupProps: {
256
+ role: "group",
257
+ "aria-label": () => access(options["aria-label"]),
258
+ "aria-labelledby": () => (hasHeading() ? headingId() : undefined),
259
+ },
260
+ };
261
+ }
262
+
263
+ // ---------------------------------------------------------------------------
264
+ // Components
265
+ // ---------------------------------------------------------------------------
266
+
267
+ export interface ListBoxContextValue {
268
+ state: ListState<unknown>;
269
+ baseId: Accessor<string>;
270
+ shouldSelectOnPressUp: Accessor<boolean | undefined>;
271
+ shouldUseVirtualFocus: Accessor<boolean | undefined>;
272
+ /**
273
+ * Where an `<Option>` written as a child registers itself.
274
+ *
275
+ * Present when the list was given no `items`: the options that render ARE the
276
+ * collection, and each one says what it is rather than reading a node.
277
+ */
278
+ staticItems?: StaticCollection | undefined;
279
+ }
280
+
281
+ const ListBoxContext = createContext<ListBoxContextValue | null>(null);
282
+ const ItemNodeContext = createContext<Node<unknown> | null>(null);
283
+
284
+ type ItemRender = (item: unknown) => Child;
285
+
286
+ /**
287
+ * The list's own item callback, so a SECTION can render its children with it.
288
+ *
289
+ * A section's options are built by the same callback as every other option;
290
+ * without this a caller would have to pass the callback to `<Section>` by hand
291
+ * at every use, and the two could disagree.
292
+ */
293
+ const ItemRenderContext = createContext<ItemRender | null>(null);
294
+
295
+ /**
296
+ * Make `<Option>` usable inside something that is not a `<ListBox>`.
297
+ *
298
+ * A select and a combobox both END in a list of options, and each owns the
299
+ * collection for its own reasons — a select closes on choosing, a combobox
300
+ * filters. Rather than three near-identical option components, they lend
301
+ * `<Option>` the state it reads.
302
+ *
303
+ * A component, not a function taking a callback: the children have to be a
304
+ * BLOCK for the binding to reach them. JSX written inside an ordinary arrow
305
+ * carries the enclosing component's scope, which is outside the one the
306
+ * binding was installed on, so every `<Option>` would look past it.
307
+ */
308
+ export function ListBoxProvider(props: Incoming<{ value: ListBoxContextValue; children?: Child }>) {
309
+ return provide(
310
+ ListBoxContext,
311
+ () => props.value(),
312
+ () => props.children as unknown,
313
+ );
314
+ }
315
+
316
+ /** The collection node the row being built is for. */
317
+ export function provideItemNode(node: Node<unknown>): void {
318
+ const owner = getOwner();
319
+ if (owner !== null) install(owner, ItemNodeContext, () => node);
320
+ }
321
+
322
+ /** The item callback the enclosing list builds its rows with. */
323
+ export function provideItemRender(render: ItemRender): void {
324
+ const owner = getOwner();
325
+ if (owner !== null) install(owner, ItemRenderContext, () => render);
326
+ }
327
+
328
+ export function useListBox(): ListBoxContextValue {
329
+ const value = getContext(ListBoxContext);
330
+ if (value === null || value === undefined) {
331
+ throw new Error("An Option must be rendered inside a ListBox.");
332
+ }
333
+ return value;
334
+ }
335
+
336
+ /** The collection node the enclosing row is for. */
337
+ export function useItemNode(): Node<unknown> {
338
+ const node = getContext(ItemNodeContext);
339
+ if (node === null || node === undefined) {
340
+ throw new Error("An Option must be rendered inside its ListBox's item callback.");
341
+ }
342
+ return node;
343
+ }
344
+
345
+ export interface SectionComponentProps extends Omit<StyleProps, "title"> {
346
+ /** The heading. A section without one is a box a screen reader cannot name. */
347
+ title?: Child;
348
+ "aria-label"?: string;
349
+ /** The heading element's own slot, for a design system naming it. */
350
+ titleSlot?: string;
351
+ /** And its class, since `class` styles the section rather than the heading. */
352
+ titleClass?: string;
353
+ "data-slot"?: string;
354
+ children?: Child;
355
+ }
356
+
357
+ /**
358
+ * A run of options under a heading.
359
+ *
360
+ * Rendered from the item callback like any other row: a section arrives there
361
+ * as its own node, and this reads the node it was given rather than being told
362
+ * what is in it.
363
+ *
364
+ * `role="group"` on a nested `<ul>` with `aria-labelledby` pointing at the
365
+ * heading, which is what lets a screen reader say "Fruit, group, 3 items". The
366
+ * heading is `role="presentation"` because a `<li>` inside a listbox that is
367
+ * not an option is one the list would otherwise count.
368
+ *
369
+ * Keyboard traversal needs nothing here: the collection links keys in document
370
+ * order ACROSS section boundaries, so Down from the last option of one section
371
+ * already reaches the first of the next.
372
+ */
373
+ export function Section(props: Incoming<SectionComponentProps>) {
374
+ const registry = getContext(ListBoxContext)?.staticItems;
375
+ if (registry !== undefined) return <StaticSection of={props} registry={registry} />;
376
+
377
+ const node = useItemNode();
378
+ const render = getContext(ItemRenderContext);
379
+ if (render === null || render === undefined) {
380
+ throw new Error("A Section must be rendered inside its list's item callback.");
381
+ }
382
+
383
+ // The hook, not a second copy of it: `listBoxSection` already decides that
384
+ // the wrapper is presentational, that the heading names the group rather
385
+ // than joining it, and that a section with no heading gets no dangling
386
+ // `aria-labelledby`.
387
+ const { itemProps, headingProps, groupProps } = listBoxSection({
388
+ heading: () => (props.title?.() === undefined ? undefined : "titled"),
389
+ "aria-label": () => props["aria-label"]?.(),
390
+ });
391
+
392
+ return (
393
+ <li {...itemProps} {...styleProps(props)} data-slot={props["data-slot"]?.() ?? "section"}>
394
+ <span
395
+ {...headingProps}
396
+ data-slot={props.titleSlot?.() ?? "section-title"}
397
+ class={props.titleClass?.()}
398
+ >
399
+ {props.title}
400
+ </span>
401
+ <ul {...groupProps}>
402
+ <For each={() => [...node.childNodes]}>
403
+ {(child: Node<unknown>) => {
404
+ provideItemNode(child);
405
+ return render(child.value);
406
+ }}
407
+ </For>
408
+ </ul>
409
+ {props.children}
410
+ </li>
411
+ );
412
+ }
413
+
414
+ interface SectionHeading {
415
+ id: Accessor<string>;
416
+ readonly name: (has: boolean) => void;
417
+ }
418
+
419
+ const SectionHeadingContext = createContext<SectionHeading | null>(null);
420
+
421
+ /**
422
+ * The id the enclosing section's heading must carry, for a heading written as
423
+ * one of the section's children rather than as its `title`.
424
+ *
425
+ * Calling it is what makes the group point at the heading, and leaving undoes
426
+ * that, so a section never names an element that is not there.
427
+ */
428
+ export function useSectionHeading(): Accessor<string> | null {
429
+ const heading = getContext(SectionHeadingContext);
430
+ if (heading === null || heading === undefined) return null;
431
+ heading.name(true);
432
+ onCleanup(() => heading.name(false));
433
+ return heading.id;
434
+ }
435
+
436
+ function StaticSection(
437
+ sectionProps: Incoming<{ of: Incoming<SectionComponentProps>; registry: StaticCollection }>,
438
+ ) {
439
+ const props = sectionProps.of();
440
+ const list = useListBox();
441
+ const section = staticItem(sectionProps.registry(), { type: "section", textValue: "" });
442
+ const headingId = id();
443
+ const [isNamed, setNamed] = createSignal(false, { ownedWrite: true });
444
+ const hasTitle = (): boolean => props.title?.() !== undefined;
445
+ const heading: SectionHeading = { id: headingId, name: setNamed };
446
+
447
+ return (
448
+ <li
449
+ role="presentation"
450
+ {...styleProps(props)}
451
+ data-slot={props["data-slot"]?.() ?? "section"}
452
+ // A section a filter has emptied still renders its heading, and a design
453
+ // system hides the whole thing off this.
454
+ data-empty={(list.state.collection().getItem(section.key)?.childNodes.length ?? 0) === 0}
455
+ ref={section.ref}
456
+ >
457
+ <span
458
+ id={hasTitle() ? headingId() : undefined}
459
+ aria-hidden="true"
460
+ data-slot={props.titleSlot?.() ?? "section-title"}
461
+ class={props.titleClass?.()}
462
+ >
463
+ {props.title}
464
+ </span>
465
+ <ul
466
+ role="group"
467
+ aria-label={props["aria-label"]?.()}
468
+ aria-labelledby={hasTitle() || isNamed() ? headingId() : undefined}
469
+ >
470
+ {
471
+ provideStaticSection(section.key, () =>
472
+ provide(
473
+ SectionHeadingContext,
474
+ () => heading,
475
+ () => props.children as unknown,
476
+ ),
477
+ ) as Child
478
+ }
479
+ </ul>
480
+ </li>
481
+ );
482
+ }
483
+
484
+ export interface ListBoxComponentProps<T> extends StyleProps, ItemAccessors<T> {
485
+ /**
486
+ * The values to render, in order.
487
+ *
488
+ * Leave it out and the `<Option>`s written as children are the collection:
489
+ * each one carries its own `value`, and nothing is rendered from data.
490
+ */
491
+ items?: Iterable<T>;
492
+ /** How one value renders, returning an `<Option>`; or the options themselves. */
493
+ children: ((item: T) => Child) | Child;
494
+ label?: Child;
495
+ description?: Child;
496
+ errorMessage?: Child;
497
+ /** @default "none" */
498
+ selectionMode?: SelectionMode;
499
+ selectedKeys?: "all" | Iterable<Key>;
500
+ defaultSelectedKeys?: "all" | Iterable<Key>;
501
+ disabledKeys?: Iterable<Key>;
502
+ disallowEmptySelection?: boolean;
503
+ shouldFocusWrap?: boolean;
504
+ orientation?: "horizontal" | "vertical";
505
+ autoFocus?: boolean | "first" | "last";
506
+ isDisabled?: boolean;
507
+ "aria-label"?: string;
508
+ "aria-labelledby"?: string;
509
+ ref?: RefTarget<HTMLUListElement>;
510
+ onSelectionChange?: (keys: "all" | Set<Key>) => void;
511
+ onAction?: (key: Key) => void;
512
+ }
513
+
514
+ /**
515
+ * ```tsx
516
+ * <ListBox
517
+ * label="Fruit"
518
+ * items={fruits()}
519
+ * selectionMode="multiple"
520
+ * onSelectionChange={(keys) => picked.set(keys)}
521
+ * >
522
+ * {(fruit) => <Option>{fruit.name}</Option>}
523
+ * </ListBox>
524
+ * ```
525
+ *
526
+ * The items are DATA. A component whose children are lazy and whose body runs
527
+ * once has no reason to render the options twice — once to discover them and
528
+ * once to show them — so the collection is derived from the values directly.
529
+ */
530
+ export function ListBox<T>(props: Incoming<ListBoxComponentProps<T>>) {
531
+ const domRef = makeRef<HTMLUListElement>();
532
+ const options = fromProps(props as unknown as Incoming<Record<string, unknown>>);
533
+ const rendered = props.items === undefined ? staticCollection() : null;
534
+
535
+ const state = listState<T>({
536
+ ...(options as ListStateOptions<T>),
537
+ ...(rendered === null
538
+ ? {}
539
+ : ({ items: rendered.entries, ...staticAccessors } as unknown as ListStateOptions<T>)),
540
+ onSelectionChange: (keys) => props.onSelectionChange?.()?.(keys),
541
+ });
542
+
543
+ // Inside a `<Virtualizer>` the list renders a WINDOW of its collection, and
544
+ // the layout — not the DOM — answers what is above, below and a page away.
545
+ const virtual = useVirtualizer();
546
+ virtual?.attach(state.collection, domRef, () => state.selectionManager().focusedKey);
547
+
548
+ const { listBoxProps, labelProps, descriptionProps, errorMessageProps, baseId } = listBox(
549
+ {
550
+ ...(options as unknown as ListBoxOptions),
551
+ ref: domRef,
552
+ isVirtualized: () => virtual !== null,
553
+ layoutDelegate: virtual?.layout,
554
+ },
555
+ state,
556
+ );
557
+
558
+ const owner = getOwner();
559
+ if (owner !== null) {
560
+ const value: ListBoxContextValue = {
561
+ state: state,
562
+ baseId,
563
+ shouldSelectOnPressUp: () => undefined,
564
+ shouldUseVirtualFocus: () => undefined,
565
+ staticItems: rendered ?? undefined,
566
+ };
567
+ install(owner, ListBoxContext, () => value);
568
+ }
569
+
570
+ const elementProps = mergeProps(
571
+ listBoxProps,
572
+ filterDOMProps(fromProps(props), { global: true }),
573
+ styleProps(props),
574
+ {
575
+ "data-testid": () => props["data-testid"]?.(),
576
+ "data-empty": () => state.collection().size === 0,
577
+ "data-virtualized": () => virtual !== null,
578
+ style: () => (virtual === null ? props.style?.() : contentStyle(virtual.contentSize())),
579
+ },
580
+ );
581
+
582
+ const render = props.children;
583
+
584
+ /** The whole collection, or the window of it the virtualiser says is on screen. */
585
+ const rows = (): Node<T>[] => {
586
+ if (virtual === null) return [...state.collection()];
587
+ const collection = state.collection();
588
+ return virtual
589
+ .visible()
590
+ .map((info: LayoutInfo) => collection.getItem(info.key))
591
+ .filter((node: Node<T> | null): node is Node<T> => node !== null);
592
+ };
593
+
594
+ provideItemRender(render as unknown as (item: unknown) => Child);
595
+
596
+ if (rendered !== null) {
597
+ return (
598
+ <>
599
+ <span {...labelProps}>{props.label}</span>
600
+ <ul {...elementProps} ref={mergeRefs(domRef.set, props.ref?.())}>
601
+ {props.children}
602
+ </ul>
603
+ <span {...descriptionProps}>{props.description}</span>
604
+ <span {...errorMessageProps}>{props.errorMessage}</span>
605
+ </>
606
+ );
607
+ }
608
+
609
+ return (
610
+ <>
611
+ <span {...labelProps}>{props.label}</span>
612
+ <ul {...elementProps} ref={mergeRefs(domRef.set, props.ref?.())}>
613
+ <For each={rows}>
614
+ {(node: Node<T>) => {
615
+ provideItemNode(node);
616
+ return render(node.value as T);
617
+ }}
618
+ </For>
619
+ </ul>
620
+ <span {...descriptionProps}>{props.description}</span>
621
+ <span {...errorMessageProps}>{props.errorMessage}</span>
622
+ </>
623
+ );
624
+ }
625
+
626
+ export interface OptionComponentProps extends StyleProps {
627
+ children?: Child;
628
+ "aria-label"?: string;
629
+ ref?: RefTarget<HTMLLIElement>;
630
+ /**
631
+ * What the option is, when it is written as a child of a list with no
632
+ * `items`: its key in the selection. Generated when left out.
633
+ */
634
+ value?: Key;
635
+ /** What a typeahead matches, for a written option. @default its own text */
636
+ textValue?: string;
637
+ /** For a written option; one rendered from data reads its item's. */
638
+ isDisabled?: boolean;
639
+ /** Keep a written option mounted and take it out of the collection. */
640
+ isHidden?: boolean;
641
+ /**
642
+ * Called when the option is acted on: a press where nothing is selectable,
643
+ * and Enter where something is, which is the split every list here makes
644
+ * between choosing a row and opening it.
645
+ */
646
+ onAction?: () => void;
647
+ }
648
+
649
+ /**
650
+ * One option. Its key, value and disabled state come from the collection node
651
+ * the enclosing {@link ListBox} is rendering, so nothing is repeated here.
652
+ */
653
+ export function Option(props: Incoming<OptionComponentProps>) {
654
+ const domRef = makeRef<HTMLLIElement>();
655
+ const list = useListBox();
656
+ const written =
657
+ list.staticItems === undefined
658
+ ? null
659
+ : staticItem(list.staticItems, {
660
+ key: props.value?.(),
661
+ textValue: () => props.textValue?.(),
662
+ props: () => ({ isDisabled: props.isDisabled?.() === true }),
663
+ isHidden: () => props.isHidden?.(),
664
+ });
665
+ const node: Pick<Node<unknown>, "key" | "props"> = written === null
666
+ ? useItemNode()
667
+ : { key: written.key, props: {} };
668
+ const virtual = useVirtualizer();
669
+
670
+ measureRow(virtual, node.key, domRef);
671
+
672
+ const { optionProps, isSelected, isFocused, isPressed, isDisabled } = option(
673
+ {
674
+ key: node.key,
675
+ ref: domRef,
676
+ baseId: list.baseId,
677
+ "aria-label": () => props["aria-label"]?.(),
678
+ isDisabled: () => props.isDisabled?.() === true || node.props?.isDisabled === true,
679
+ shouldSelectOnPressUp: list.shouldSelectOnPressUp,
680
+ shouldUseVirtualFocus: list.shouldUseVirtualFocus,
681
+ isVirtualized: () => virtual !== null,
682
+ onAction: () => props.onAction?.()?.(),
683
+ hasAction: () => props.onAction?.() !== undefined,
684
+ },
685
+ list.state,
686
+ );
687
+
688
+ const { hoverProps, isHovered } = hover({ isDisabled });
689
+ const { focusProps, isFocusVisible } = focusRing();
690
+
691
+ const elementProps = mergeProps(
692
+ optionProps,
693
+ hoverProps,
694
+ focusProps,
695
+ filterDOMProps(fromProps(props), { global: true, labelable: true }),
696
+ styleProps(props),
697
+ {
698
+ "data-selected": isSelected,
699
+ "data-focused": isFocused,
700
+ "data-focus-visible": isFocusVisible,
701
+ "data-pressed": isPressed,
702
+ "data-hovered": isHovered,
703
+ "data-disabled": isDisabled,
704
+ hidden: () => props.isHidden?.() === true || undefined,
705
+ "data-testid": () => props["data-testid"]?.(),
706
+ // Positioned by the LAYOUT: the rows above it are not rendered, so
707
+ // document flow has nothing to place it against.
708
+ style: () => {
709
+ if (virtual === null) return props.style?.();
710
+ const info = virtual.layout.getLayoutInfo(node.key);
711
+ return info === null ? props.style?.() : rowStyle(info);
712
+ },
713
+ },
714
+ );
715
+
716
+ return (
717
+ <li {...elementProps} ref={mergeRefs(domRef.set, written?.ref, props.ref?.())}>
718
+ {props.children}
719
+ </li>
720
+ );
721
+ }