@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.
- package/LICENSE +21 -0
- package/README.md +293 -2
- package/package.json +347 -4
- package/src/breadcrumbs.tsx +296 -0
- package/src/button.tsx +342 -0
- package/src/calendar.tsx +1389 -0
- package/src/checkbox.tsx +570 -0
- package/src/collections.ts +976 -0
- package/src/color.ts +562 -0
- package/src/colorpicker.tsx +1478 -0
- package/src/combobox.tsx +2481 -0
- package/src/command.tsx +1184 -0
- package/src/date.ts +652 -0
- package/src/datefield.tsx +951 -0
- package/src/datepicker.tsx +556 -0
- package/src/dialog.tsx +890 -0
- package/src/disclosure.tsx +659 -0
- package/src/dom.ts +706 -0
- package/src/drawer.ts +674 -0
- package/src/focus.ts +1370 -0
- package/src/form.tsx +94 -0
- package/src/gridlist.tsx +563 -0
- package/src/i18n.ts +823 -0
- package/src/index.ts +1270 -0
- package/src/interactions/description.ts +73 -0
- package/src/interactions/flags.ts +35 -0
- package/src/interactions/focus-events.ts +218 -0
- package/src/interactions/focusable.ts +86 -0
- package/src/interactions/hover.ts +213 -0
- package/src/interactions/interact-outside.ts +123 -0
- package/src/interactions/keyboard.ts +105 -0
- package/src/interactions/listeners.ts +78 -0
- package/src/interactions/long-press.ts +160 -0
- package/src/interactions/modality.ts +416 -0
- package/src/interactions/move.ts +257 -0
- package/src/interactions/open-link.ts +193 -0
- package/src/interactions/press.ts +898 -0
- package/src/interactions/prevent-focus.ts +102 -0
- package/src/interactions/scroll-wheel.ts +43 -0
- package/src/interactions/text-selection.ts +77 -0
- package/src/interactions.ts +81 -0
- package/src/label.ts +128 -0
- package/src/link.tsx +381 -0
- package/src/listbox.tsx +721 -0
- package/src/live.ts +204 -0
- package/src/menu.tsx +2290 -0
- package/src/menubar.tsx +575 -0
- package/src/navigation.ts +735 -0
- package/src/numberfield.tsx +838 -0
- package/src/otp.ts +430 -0
- package/src/overlays.ts +1247 -0
- package/src/platform.ts +74 -0
- package/src/presence.ts +164 -0
- package/src/questionnaire.tsx +1712 -0
- package/src/radio.tsx +567 -0
- package/src/register-dom.ts +12 -0
- package/src/scroller.ts +1165 -0
- package/src/select.tsx +1665 -0
- package/src/selection.ts +1415 -0
- package/src/slider.tsx +1042 -0
- package/src/splitter.ts +1152 -0
- package/src/static-collection.ts +211 -0
- package/src/switch.tsx +186 -0
- package/src/table.tsx +0 -0
- package/src/tabs.tsx +1018 -0
- package/src/tag.tsx +452 -0
- package/src/textfield.tsx +417 -0
- package/src/toast.ts +658 -0
- package/src/toggle-input.tsx +48 -0
- package/src/toggle.ts +321 -0
- package/src/togglegroup.ts +365 -0
- package/src/toolbar.tsx +179 -0
- package/src/tooltip.tsx +657 -0
- package/src/utils.ts +758 -0
- package/src/validation.ts +447 -0
- package/src/virtualizer.tsx +674 -0
package/src/listbox.tsx
ADDED
|
@@ -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
|
+
}
|