@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,837 @@
1
+ /**
2
+ * Rendering only the rows that are on screen.
3
+ *
4
+ * A collection of ten thousand rows is ten thousand elements, ten thousand
5
+ * press handlers and ten thousand entries in the accessibility tree, and a
6
+ * browser will not hold that at sixty frames a second. Virtualisation renders
7
+ * the visible window and lies about the rest: the scroll container is sized to
8
+ * the WHOLE collection so the scrollbar is honest, and each visible row is
9
+ * positioned absolutely where it would have been.
10
+ *
11
+ * Three things follow, and all three are why this cannot be a generic "render
12
+ * a window of an array" helper:
13
+ *
14
+ * - **A screen reader is told the truth.** `aria-setsize` and `aria-posinset`
15
+ * name the item's place in the WHOLE collection, not in the window; without
16
+ * them a reader announces "1 of 12" halfway down a list of ten thousand.
17
+ * - **Keyboard navigation stops being about the DOM.** Page Up and Page Down
18
+ * move by a viewport, and the elements a viewport away do not exist. That is
19
+ * what {@link LayoutDelegate} is for, and why a {@link Layout} is one.
20
+ * - **Focus must survive scrolling away.** The focused row can be unmounted
21
+ * while it still holds focus, so the collection keeps its key and restores
22
+ * it when the row comes back.
23
+ *
24
+ * ## What this is not
25
+ *
26
+ * react-aria recycles view objects (`ReusableView`) so React does not remount
27
+ * a row that moved. Nothing here does, and nothing needs to: `<For>` keys rows
28
+ * by item, so a row that stays in the window keeps its element, its scope and
29
+ * its state across a scroll, and one that leaves is disposed exactly once.
30
+ *
31
+ * There is no drag-and-drop layout either, because this package has no
32
+ * drag-and-drop.
33
+ */
34
+
35
+ import {
36
+ type Accessor,
37
+ type Child,
38
+ createContext,
39
+ createEffect,
40
+ getContext,
41
+ type Incoming,
42
+ provide,
43
+ createSignal,
44
+ untrack,
45
+ } from "@barqjs/core";
46
+ import { isServer } from "@barqjs/web";
47
+ import { ListCollection } from "./collections.ts";
48
+ import type { Collection, Key, LayoutDelegate, Node, Rect, Size } from "./collections.ts";
49
+ import { access, type MaybeAccessor } from "./utils.ts";
50
+ import { addEvent, contains, ownerWindow, propagationTargets } from "./dom.ts";
51
+ import type { ElementRef } from "./interactions/press.ts";
52
+ import type { DropTarget, ItemDropTarget } from "./dnd/types.ts";
53
+
54
+ // ---------------------------------------------------------------------------
55
+ // Geometry
56
+ // ---------------------------------------------------------------------------
57
+
58
+ export interface Point {
59
+ x: number;
60
+ y: number;
61
+ }
62
+
63
+ /** A rectangle from its edges, which is how a layout thinks about one. */
64
+ export function rect(x: number, y: number, width: number, height: number): Rect {
65
+ return { x, y, width, height };
66
+ }
67
+
68
+ export function rectMaxX(r: Rect): number {
69
+ return r.x + r.width;
70
+ }
71
+
72
+ export function rectMaxY(r: Rect): number {
73
+ return r.y + r.height;
74
+ }
75
+
76
+ /** Whether two rectangles overlap at all. Touching edges do not count. */
77
+ export function rectIntersects(a: Rect, b: Rect): boolean {
78
+ return a.x < rectMaxX(b) && rectMaxX(a) > b.x && a.y < rectMaxY(b) && rectMaxY(a) > b.y;
79
+ }
80
+
81
+ export function rectContainsPoint(r: Rect, point: Point): boolean {
82
+ return point.x >= r.x && point.x <= rectMaxX(r) && point.y >= r.y && point.y <= rectMaxY(r);
83
+ }
84
+
85
+ export function rectEquals(a: Rect, b: Rect): boolean {
86
+ return a.x === b.x && a.y === b.y && a.width === b.width && a.height === b.height;
87
+ }
88
+
89
+ // ---------------------------------------------------------------------------
90
+ // What a layout says about one item
91
+ // ---------------------------------------------------------------------------
92
+
93
+ export interface LayoutInfo {
94
+ /** Matches the collection node's `type`: "item", "section", "header". */
95
+ type: string;
96
+ key: Key;
97
+ rect: Rect;
98
+ parentKey: Key | null;
99
+ /**
100
+ * The size is a GUESS until the row has been in the DOM once.
101
+ *
102
+ * A list of rows whose height depends on their content cannot be laid out
103
+ * without rendering them, and rendering them all is the thing being avoided.
104
+ * So the layout guesses, the virtualiser measures what it rendered, and the
105
+ * guess is replaced — which moves everything below it, which is why
106
+ * `updateItemSize` returns whether anything changed.
107
+ */
108
+ isEstimated: boolean;
109
+ /** Stays put while its section scrolls under it. */
110
+ isSticky: boolean;
111
+ }
112
+
113
+ export function layoutInfo(
114
+ type: string,
115
+ key: Key,
116
+ bounds: Rect,
117
+ extra: Partial<Omit<LayoutInfo, "type" | "key" | "rect">> = {},
118
+ ): LayoutInfo {
119
+ return {
120
+ type,
121
+ key,
122
+ rect: bounds,
123
+ parentKey: extra.parentKey ?? null,
124
+ isEstimated: extra.isEstimated ?? false,
125
+ isSticky: extra.isSticky ?? false,
126
+ };
127
+ }
128
+
129
+ // ---------------------------------------------------------------------------
130
+ // The layout
131
+ // ---------------------------------------------------------------------------
132
+
133
+ export interface LayoutContext {
134
+ collection: Collection<unknown>;
135
+ /** What the scroll container shows, in content coordinates. */
136
+ visibleRect: Rect;
137
+ /**
138
+ * The size of the scroll container's box. @default the visible rectangle's
139
+ *
140
+ * Larger than the visible rectangle when the page scrolls the container
141
+ * rather than the container itself: rows are as wide as the container,
142
+ * however little of it is on screen.
143
+ */
144
+ size?: Size;
145
+ }
146
+
147
+ /**
148
+ * Where every item in a collection goes.
149
+ *
150
+ * It is a {@link LayoutDelegate} as well, which is the whole point: once the
151
+ * rows are not all in the DOM, "what is the key above this one" and "how far
152
+ * is a page" have to be answered from the layout rather than by measuring
153
+ * elements that are not there.
154
+ */
155
+ export abstract class Layout implements LayoutDelegate {
156
+ protected context: LayoutContext = {
157
+ collection: emptyCollection(),
158
+ visibleRect: rect(0, 0, 0, 0),
159
+ };
160
+
161
+ /** Recompute. Called whenever the collection or the visible rectangle moves. */
162
+ update(context: LayoutContext): void {
163
+ this.context = context;
164
+ }
165
+
166
+ /** The window moved but the layout did not: keep the rectangle current. */
167
+ setVisibleRect(area: Rect): void {
168
+ this.context = { ...this.context, visibleRect: area };
169
+ }
170
+
171
+ abstract getLayoutInfo(key: Key): LayoutInfo | null;
172
+
173
+ /** Every item overlapping the rectangle, in collection order. */
174
+ abstract getVisibleLayoutInfos(area: Rect): LayoutInfo[];
175
+
176
+ abstract getContentSize(): Size;
177
+
178
+ /**
179
+ * Whether a change in the visible rectangle needs a fresh layout.
180
+ *
181
+ * Only a resize by default: scrolling moves the window over a layout that
182
+ * has not changed. A layout with sticky headers overrides it to `true`,
183
+ * because where a header sits depends on where the scroll is.
184
+ */
185
+ shouldInvalidate(next: Rect, previous: Rect): boolean {
186
+ return next.width !== previous.width || next.height !== previous.height;
187
+ }
188
+
189
+ /** The real size of a row that was measured. Returns whether it moved anything. */
190
+ updateItemSize?(key: Key, size: Size): boolean;
191
+
192
+ /**
193
+ * The drop target under a point, the point measured from the scrolling
194
+ * element's own corner. A layout that answers is what lets a virtualised
195
+ * collection take a drop: the rows a point may fall between are mostly not
196
+ * in the document to be measured.
197
+ */
198
+ getDropTargetFromPoint?(
199
+ x: number,
200
+ y: number,
201
+ isValidDropTarget: (target: DropTarget) => boolean,
202
+ ): DropTarget | null;
203
+
204
+ /** Where the indicator for a position before or after an item is drawn. */
205
+ getDropTargetLayoutInfo?(target: ItemDropTarget): LayoutInfo | null;
206
+
207
+ getItemRect(key: Key): Rect | null {
208
+ return this.getLayoutInfo(key)?.rect ?? null;
209
+ }
210
+
211
+ getVisibleRect(): Rect {
212
+ return this.context.visibleRect;
213
+ }
214
+
215
+ getKeyRange(from: Key, to: Key): Key[] {
216
+ const start = this.getLayoutInfo(from);
217
+ const end = this.getLayoutInfo(to);
218
+ if (start === null || end === null) return [];
219
+
220
+ const top = Math.min(start.rect.y, end.rect.y);
221
+ const bottom = Math.max(rectMaxY(start.rect), rectMaxY(end.rect));
222
+ return this.getVisibleLayoutInfos(rect(0, top, this.getContentSize().width, bottom - top))
223
+ .filter((info) => info.type === "item")
224
+ .map((info) => info.key);
225
+ }
226
+ }
227
+
228
+ /** What a layout holds before it has been given anything to lay out. */
229
+ function emptyCollection(): Collection<unknown> {
230
+ return new ListCollection<unknown>([]);
231
+ }
232
+
233
+ // ---------------------------------------------------------------------------
234
+ // A list of rows
235
+ // ---------------------------------------------------------------------------
236
+
237
+ /** How near a row's edge a point counts as between rows, where a drop on the row is allowed. */
238
+ const DROP_EDGE = 10;
239
+ /** The height an indicator between two rows is given. Its look is the caller's. */
240
+ const DROP_INDICATOR_THICKNESS = 2;
241
+
242
+ export interface ListLayoutOptions {
243
+ /** A fixed height for every row. Leave it out to estimate and measure. */
244
+ rowHeight?: number;
245
+ /** The starting guess when `rowHeight` is not given. @default 48 */
246
+ estimatedRowHeight?: number;
247
+ /** A fixed height for a section's heading. */
248
+ headingHeight?: number;
249
+ /** @default 36 */
250
+ estimatedHeadingHeight?: number;
251
+ /** Space between rows. @default 0 */
252
+ gap?: number;
253
+ /** Space around the whole list. @default 0 */
254
+ padding?: number;
255
+ /** Keep a section's heading in view while its rows scroll under it. */
256
+ stickyHeadings?: boolean;
257
+ }
258
+
259
+ /**
260
+ * Rows stacked vertically, with optional section headings.
261
+ *
262
+ * Heights may be fixed or estimated. Estimated is the honest default for text
263
+ * that wraps: the layout guesses, the virtualiser measures what it actually
264
+ * rendered, and every row below the corrected one moves. That correction is
265
+ * why the scrollbar drifts slightly on first scroll through a list of
266
+ * estimated rows, and why `rowHeight` is worth giving when it is known.
267
+ */
268
+ export class ListLayout extends Layout {
269
+ #options: Required<ListLayoutOptions>;
270
+ #infos = new Map<Key, LayoutInfo>();
271
+ /** In collection order, so a visible range is a slice rather than a scan. */
272
+ #order: LayoutInfo[] = [];
273
+ /** A measured height, and the width it was measured at. */
274
+ #measured = new Map<Key, { height: number; width: number }>();
275
+ #width = 0;
276
+ #contentHeight = 0;
277
+
278
+ constructor(options: ListLayoutOptions = {}) {
279
+ super();
280
+ this.#options = {
281
+ rowHeight: options.rowHeight ?? Number.NaN,
282
+ estimatedRowHeight: options.estimatedRowHeight ?? 48,
283
+ headingHeight: options.headingHeight ?? Number.NaN,
284
+ estimatedHeadingHeight: options.estimatedHeadingHeight ?? 36,
285
+ gap: options.gap ?? 0,
286
+ padding: options.padding ?? 0,
287
+ stickyHeadings: options.stickyHeadings ?? false,
288
+ };
289
+ }
290
+
291
+ override shouldInvalidate(next: Rect, previous: Rect): boolean {
292
+ if (this.#options.stickyHeadings) return true;
293
+ return super.shouldInvalidate(next, previous);
294
+ }
295
+
296
+ override update(context: LayoutContext): void {
297
+ super.update(context);
298
+
299
+ const width = Math.max(
300
+ 0,
301
+ (context.size?.width ?? context.visibleRect.width) - this.#options.padding * 2,
302
+ );
303
+ this.#width = width;
304
+ const previous = this.#infos;
305
+ this.#infos = new Map();
306
+ this.#order = [];
307
+
308
+ let y = this.#options.padding;
309
+
310
+ const place = (node: Node<unknown>, parentKey: Key | null, isHeading: boolean): void => {
311
+ const height = this.#heightOf(node.key, isHeading);
312
+ const info = layoutInfo(node.type, node.key, rect(this.#options.padding, y, width, height), {
313
+ parentKey,
314
+ isEstimated: this.#isEstimated(node.key, isHeading),
315
+ isSticky: isHeading && this.#options.stickyHeadings,
316
+ });
317
+ this.#infos.set(node.key, info);
318
+ this.#order.push(info);
319
+ y += height + this.#options.gap;
320
+ };
321
+
322
+ const walk = (nodes: Iterable<Node<unknown>>, parentKey: Key | null): void => {
323
+ for (const node of nodes) {
324
+ if (node.type === "section") {
325
+ place(node, parentKey, true);
326
+ walk(context.collection.getChildren?.(node.key) ?? [], node.key);
327
+ } else {
328
+ place(node, parentKey, false);
329
+ }
330
+ }
331
+ };
332
+
333
+ walk(context.collection, null);
334
+
335
+ // The trailing gap is between rows, not after the last one.
336
+ this.#contentHeight =
337
+ Math.max(this.#options.padding, y - this.#options.gap) + this.#options.padding;
338
+
339
+ // A measurement survives a collection change: the row is the same row.
340
+ // It does not survive a change of width, which `#isEstimated` has said.
341
+ for (const [key, info] of this.#infos) {
342
+ const old = previous.get(key);
343
+ if (old !== undefined && !old.isEstimated && old.rect.width === info.rect.width) {
344
+ info.isEstimated = false;
345
+ }
346
+ }
347
+ }
348
+
349
+ /**
350
+ * Whether a row's height is a guess.
351
+ *
352
+ * A height measured at another width is one: text that wraps takes more or
353
+ * fewer lines when the row narrows, so the old height is kept as the guess
354
+ * and the row is measured again. Left as measured, the row would be drawn
355
+ * at a fixed height that no longer fits it and never observed again.
356
+ */
357
+ #isEstimated(key: Key, isHeading: boolean): boolean {
358
+ const fixed = !Number.isNaN(isHeading ? this.#options.headingHeight : this.#options.rowHeight);
359
+ const measured = this.#measured.get(key);
360
+ if (measured === undefined) return !fixed;
361
+ return !fixed && measured.width !== this.#width;
362
+ }
363
+
364
+ #heightOf(key: Key, isHeading: boolean): number {
365
+ const measured = this.#measured.get(key)?.height;
366
+ if (measured !== undefined) return measured;
367
+ const fixed = isHeading ? this.#options.headingHeight : this.#options.rowHeight;
368
+ if (!Number.isNaN(fixed)) return fixed;
369
+ return isHeading ? this.#options.estimatedHeadingHeight : this.#options.estimatedRowHeight;
370
+ }
371
+
372
+ override getLayoutInfo(key: Key): LayoutInfo | null {
373
+ return this.#infos.get(key) ?? null;
374
+ }
375
+
376
+ override getVisibleLayoutInfos(area: Rect): LayoutInfo[] {
377
+ const visible: LayoutInfo[] = [];
378
+ for (const info of this.#order) {
379
+ if (info.isSticky || rectIntersects(info.rect, area)) visible.push(info);
380
+ // In order, so once past the bottom there is nothing left — except a
381
+ // sticky heading, which is why the loop does not break early when
382
+ // headings stick.
383
+ else if (info.rect.y > rectMaxY(area) && !this.#options.stickyHeadings) break;
384
+ }
385
+ return visible;
386
+ }
387
+
388
+ override getContentSize(): Size {
389
+ const width = this.context.size?.width ?? this.context.visibleRect.width;
390
+ return { width, height: this.#contentHeight };
391
+ }
392
+
393
+ override updateItemSize(key: Key, size: Size): boolean {
394
+ const known = this.#measured.get(key);
395
+ // The width the layout gave the row, which is what it was measured at.
396
+ const width = this.#infos.get(key)?.rect.width ?? this.#width;
397
+ if (known !== undefined && known.height === size.height && known.width === width) return false;
398
+ this.#measured.set(key, { height: size.height, width });
399
+ return true;
400
+ }
401
+
402
+ override getDropTargetFromPoint(
403
+ x: number,
404
+ y: number,
405
+ isValidDropTarget: (target: DropTarget) => boolean,
406
+ ): DropTarget | null {
407
+ const visible = this.context.visibleRect;
408
+ const at = y + visible.y;
409
+ const gap = this.#options.gap;
410
+ // A point in the gap between two rows belongs to the nearer of them.
411
+ const search = rect(x + visible.x, Math.max(0, at - gap), 1, Math.max(1, gap * 2));
412
+
413
+ let nearest: LayoutInfo | null = null;
414
+ let distance = Number.POSITIVE_INFINITY;
415
+ for (const info of this.#order) {
416
+ if (info.type !== "item" || !rectIntersects(info.rect, search)) continue;
417
+ const away = Math.min(Math.abs(info.rect.y - at), Math.abs(rectMaxY(info.rect) - at));
418
+ if (away < distance) {
419
+ distance = away;
420
+ nearest = info;
421
+ }
422
+ }
423
+ if (nearest === null || this.context.collection.size === 0) return { type: "root" };
424
+
425
+ const start = nearest.rect.y;
426
+ const end = rectMaxY(nearest.rect);
427
+ const on: ItemDropTarget = { type: "item", key: nearest.key, dropPosition: "on" };
428
+ const before: ItemDropTarget = { ...on, dropPosition: "before" };
429
+ const after: ItemDropTarget = { ...on, dropPosition: "after" };
430
+
431
+ if (!isValidDropTarget(on)) {
432
+ if (at <= start + nearest.rect.height / 2 && isValidDropTarget(before)) return before;
433
+ return isValidDropTarget(after) ? after : on;
434
+ }
435
+ // Still between rows within reach of an edge, where a drop on is allowed.
436
+ if (at <= start + DROP_EDGE && isValidDropTarget(before)) return before;
437
+ if (at >= end - DROP_EDGE && isValidDropTarget(after)) return after;
438
+ return on;
439
+ }
440
+
441
+ override getDropTargetLayoutInfo(target: ItemDropTarget): LayoutInfo | null {
442
+ let info = this.#infos.get(target.key);
443
+ if (info === undefined) return null;
444
+
445
+ if (target.dropPosition === "after") {
446
+ // After the last row of the item's own branch, which is where an
447
+ // expanded parent ends.
448
+ const collection = this.context.collection;
449
+ const level = collection.getItem(target.key)?.level ?? 0;
450
+ let next = collection.getKeyAfter(target.key);
451
+ while (next !== null) {
452
+ const node = collection.getItem(next);
453
+ if (node === null || node === undefined || (node.level ?? 0) <= level) break;
454
+ info = this.#infos.get(next) ?? info;
455
+ next = collection.getKeyAfter(next);
456
+ }
457
+ }
458
+
459
+ const y =
460
+ target.dropPosition === "before"
461
+ ? Math.max(0, info.rect.y - DROP_INDICATOR_THICKNESS / 2)
462
+ : target.dropPosition === "after"
463
+ ? rectMaxY(info.rect) - DROP_INDICATOR_THICKNESS / 2
464
+ : info.rect.y;
465
+ const height = target.dropPosition === "on" ? info.rect.height : DROP_INDICATOR_THICKNESS;
466
+ return layoutInfo("item", target.key, rect(info.rect.x, y, info.rect.width, height), {
467
+ parentKey: info.parentKey,
468
+ });
469
+ }
470
+
471
+ override getKeyRange(from: Key, to: Key): Key[] {
472
+ const start = this.#infos.get(from);
473
+ const end = this.#infos.get(to);
474
+ if (start === undefined || end === undefined) return [];
475
+
476
+ const first = this.#order.indexOf(start);
477
+ const last = this.#order.indexOf(end);
478
+ const [a, b] = first <= last ? [first, last] : [last, first];
479
+ return this.#order
480
+ .slice(a, b + 1)
481
+ .filter((info) => info.type === "item")
482
+ .map((info) => info.key);
483
+ }
484
+ }
485
+
486
+ /** `new ListLayout(...)`, for a call site that reads better without `new`. */
487
+ export function listLayout(options: ListLayoutOptions = {}): ListLayout {
488
+ return new ListLayout(options);
489
+ }
490
+
491
+ // ---------------------------------------------------------------------------
492
+ // The state
493
+ // ---------------------------------------------------------------------------
494
+
495
+ export interface VirtualizerOptions {
496
+ layout: Layout;
497
+ collection: Accessor<Collection<unknown>>;
498
+ /** The scrolling element. */
499
+ ref: ElementRef;
500
+ /**
501
+ * How much to render beyond the visible rectangle, as a fraction of it.
502
+ *
503
+ * Zero renders exactly what is on screen, and a fast scroll then shows blank
504
+ * space for a frame. @default 1
505
+ */
506
+ overscan?: MaybeAccessor<number | undefined>;
507
+ /** Always render these, wherever they are: the focused row is one. */
508
+ persistedKeys?: MaybeAccessor<Iterable<Key> | undefined>;
509
+ }
510
+
511
+ export interface VirtualizerState {
512
+ /** What to render, in collection order. */
513
+ visible: Accessor<LayoutInfo[]>;
514
+ /** The size the scroll container must claim for the scrollbar to be honest. */
515
+ contentSize: Accessor<Size>;
516
+ visibleRect: Accessor<Rect>;
517
+ /** Report a rendered row's real size, for a layout that estimated it. */
518
+ measure: (key: Key, size: Size) => void;
519
+ layout: Layout;
520
+ }
521
+
522
+ /**
523
+ * Which rows are on screen, kept up to date as the container scrolls.
524
+ *
525
+ * The scroll listener is passive and does no layout of its own: it reads
526
+ * `scrollTop` and `clientHeight`, which the browser already knows, and writes
527
+ * a signal. Everything else falls out of that reactively.
528
+ */
529
+ export function virtualizer(options: VirtualizerOptions): VirtualizerState {
530
+ const [visibleRect, writeVisibleRect] = createSignal<Rect>(rect(0, 0, 0, 0));
531
+ const [size, writeSize] = createSignal<Size>({ width: 0, height: 0 });
532
+ const [revision, setRevision] = createSignal(0);
533
+
534
+ const overscan = (): number => access(options.overscan) ?? 1;
535
+
536
+ /**
537
+ * What of the container is on screen: its own scroll position, clipped to
538
+ * the window.
539
+ *
540
+ * A container that grows with its content never scrolls itself; the page
541
+ * does. Its whole height would then count as visible and every row would
542
+ * render, so the part of it above the viewport is skipped and no more than
543
+ * a viewport is taken. Scrollers between it and the page are not measured,
544
+ * only their scroll positions, which can render up to a viewport more than
545
+ * is shown and never less.
546
+ */
547
+ const read = (element: HTMLElement): void => {
548
+ const view = ownerWindow(element);
549
+ const bounds = element.getBoundingClientRect();
550
+ const offsetX = bounds.left < 0 ? -bounds.left : 0;
551
+ const offsetY = bounds.top < 0 ? -bounds.top : 0;
552
+ const next = rect(
553
+ offsetX + element.scrollLeft,
554
+ offsetY + element.scrollTop,
555
+ Math.max(0, Math.min(element.clientWidth - offsetX, view.innerWidth)),
556
+ Math.max(0, Math.min(element.clientHeight - offsetY, view.innerHeight)),
557
+ );
558
+ const box = { width: element.clientWidth, height: element.clientHeight };
559
+ const known = untrack(size);
560
+ if (box.width !== known.width || box.height !== known.height) writeSize(box);
561
+ if (!rectEquals(next, untrack(visibleRect))) writeVisibleRect(next);
562
+ };
563
+
564
+ if (!isServer) {
565
+ createEffect(
566
+ () => access(options.ref) as HTMLElement | null,
567
+ (element) => {
568
+ if (element === null) return undefined;
569
+
570
+ const measure = (): void => read(element);
571
+ measure();
572
+ // Captured at the window, so the page or any scroller around the
573
+ // container moving it is seen as well as the container's own scroll.
574
+ const onScroll = (event: Event): void => {
575
+ const target = event.target;
576
+ if (target instanceof Node && !contains(target, element)) return;
577
+ measure();
578
+ };
579
+ const stopScroll = addEvent(propagationTargets(element), "scroll", onScroll, {
580
+ capture: true,
581
+ passive: true,
582
+ });
583
+ const stopResize = addEvent(ownerWindow(element), "resize", measure);
584
+
585
+ const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(measure);
586
+ observer?.observe(element);
587
+
588
+ return () => {
589
+ stopScroll();
590
+ stopResize();
591
+ observer?.disconnect();
592
+ };
593
+ },
594
+ );
595
+ }
596
+
597
+ /**
598
+ * The layout, brought up to date.
599
+ *
600
+ * `update` runs when the collection changes, when a measurement corrected an
601
+ * estimate, or when the layout says the new visible rectangle matters — a
602
+ * resize, or any scroll at all when headings stick. A plain scroll otherwise
603
+ * only moves the window over a layout that has not changed, but the
604
+ * rectangle is still stored, because `getVisibleRect` is what answers the
605
+ * keyboard delegate's "how far is a page".
606
+ */
607
+ let lastRect = rect(0, 0, 0, 0);
608
+ let lastCollection: Collection<unknown> | null = null;
609
+ const laidOut = (): Layout => {
610
+ revision();
611
+ const area = visibleRect();
612
+ const box = size();
613
+ const collection = options.collection();
614
+ // The layout is asked about the container's box: the window clipping it
615
+ // changes what is on screen, not where anything goes.
616
+ const sized = rect(area.x, area.y, box.width, box.height);
617
+ const stale = collection !== lastCollection || options.layout.shouldInvalidate(sized, lastRect);
618
+
619
+ if (stale) options.layout.update({ collection, visibleRect: area, size: box });
620
+ else options.layout.setVisibleRect(area);
621
+
622
+ lastCollection = collection;
623
+ lastRect = sized;
624
+ return options.layout;
625
+ };
626
+
627
+ const visible = (): LayoutInfo[] => {
628
+ const layout = laidOut();
629
+ const area = visibleRect();
630
+ const margin = area.height * overscan();
631
+ const window_ = rect(area.x, area.y - margin, area.width, area.height + margin * 2);
632
+
633
+ const found = layout.getVisibleLayoutInfos(window_);
634
+ const held = [...(access(options.persistedKeys) ?? [])];
635
+ if (held.length === 0) return found;
636
+
637
+ const seen = new Set(found.map((info) => info.key));
638
+ for (const key of held) {
639
+ if (seen.has(key)) continue;
640
+ const info = layout.getLayoutInfo(key);
641
+ // Appended rather than inserted in order: a persisted row is off screen,
642
+ // so where it sits among the visible ones says nothing. Its position
643
+ // comes from its rect, not from the order it was rendered in.
644
+ if (info !== null) found.push(info);
645
+ }
646
+ return found;
647
+ };
648
+
649
+ const contentSize = (): Size => laidOut().getContentSize();
650
+
651
+ const measure = (key: Key, measured: Size): void => {
652
+ if (options.layout.updateItemSize?.(key, measured) === true) setRevision((n) => n + 1);
653
+ };
654
+
655
+ return { visible, contentSize, visibleRect, measure, layout: options.layout };
656
+ }
657
+
658
+ // ---------------------------------------------------------------------------
659
+ // The seam a collection component renders through
660
+ // ---------------------------------------------------------------------------
661
+
662
+ export interface VirtualizerValue {
663
+ layout: Layout;
664
+ /**
665
+ * Told by the collection below what it holds and what scrolls.
666
+ *
667
+ * The virtualiser is written OUTSIDE the collection so a caller can choose
668
+ * the layout, but the collection and the scrolling element are the
669
+ * collection's own. So this is the handshake: the wrapper provides the
670
+ * layout, the collection hands back the two things only it knows.
671
+ */
672
+ attach: (
673
+ collection: Accessor<Collection<unknown>>,
674
+ ref: ElementRef,
675
+ focusedKey: Accessor<Key | null>,
676
+ /** Rows the collection needs kept, as the one a drop is aimed at. */
677
+ persistedKeys?: Accessor<Iterable<Key>>,
678
+ ) => void;
679
+ /** What to render, in collection order. */
680
+ visible: Accessor<LayoutInfo[]>;
681
+ contentSize: Accessor<Size>;
682
+ measure: (key: Key, size: Size) => void;
683
+ /** Whether rows should measure themselves: only when the layout estimated. */
684
+ shouldMeasure: Accessor<boolean>;
685
+ }
686
+
687
+ const VirtualizerContext = createContext<VirtualizerValue | null>(null);
688
+
689
+ /** The enclosing {@link Virtualizer}, if the collection is inside one. */
690
+ export function useVirtualizer(): VirtualizerValue | null {
691
+ return getContext(VirtualizerContext) ?? null;
692
+ }
693
+
694
+ /**
695
+ * The style the scrolling element carries, so the scrollbar tells the truth.
696
+ *
697
+ * `position: relative` because the rows inside are positioned absolutely
698
+ * against it, and the height of the WHOLE collection because that is what the
699
+ * scrollbar is measuring — the rendered rows are a fraction of it.
700
+ */
701
+ export function contentStyle(size: Size): Record<string, string> {
702
+ return { position: "relative", height: `${size.height}px` };
703
+ }
704
+
705
+ /**
706
+ * The style a virtualised row carries.
707
+ *
708
+ * Absolute, from the layout. The rows above it are not rendered, so document
709
+ * flow has nothing to go on; where the row belongs is what the layout says.
710
+ * A row whose height was ESTIMATED is left to size itself, so it can be
711
+ * measured and the estimate corrected.
712
+ */
713
+ export function rowStyle(info: LayoutInfo): Record<string, string> {
714
+ return {
715
+ position: info.isSticky ? "sticky" : "absolute",
716
+ top: `${info.rect.y}px`,
717
+ left: `${info.rect.x}px`,
718
+ width: `${info.rect.width}px`,
719
+ ...(info.isEstimated ? {} : { height: `${info.rect.height}px` }),
720
+ ...(info.isSticky ? { zIndex: "1" } : {}),
721
+ };
722
+ }
723
+
724
+ /**
725
+ * Measure a virtualised row and report its real height.
726
+ *
727
+ * Only for a layout that ESTIMATED: a fixed-height layout already knows, and
728
+ * observing every row to be told what it was told would cost more than the
729
+ * virtualisation saves.
730
+ */
731
+ export function measureRow(virtual: VirtualizerValue | null, key: Key, ref: ElementRef): void {
732
+ if (isServer || virtual === null) return;
733
+
734
+ createEffect(
735
+ () => (virtual.shouldMeasure() ? (access(ref) as HTMLElement | null) : null),
736
+ (element) => {
737
+ if (element === null) return undefined;
738
+
739
+ const report = (): void => {
740
+ virtual.measure(key, { width: element.offsetWidth, height: element.offsetHeight });
741
+ };
742
+ report();
743
+
744
+ if (typeof ResizeObserver === "undefined") return undefined;
745
+ const observer = new ResizeObserver(report);
746
+ observer.observe(element);
747
+ return () => observer.disconnect();
748
+ },
749
+ );
750
+ }
751
+
752
+ export interface VirtualizerComponentProps {
753
+ /** Where the rows go. {@link listLayout} builds the usual one. */
754
+ layout: Layout;
755
+ /** See {@link VirtualizerOptions.overscan}. @default 1 */
756
+ overscan?: number;
757
+ /** Always rendered, wherever they are. The focused row is added anyway. */
758
+ persistedKeys?: Iterable<Key>;
759
+ children?: Child;
760
+ }
761
+
762
+ /**
763
+ * Render only the rows that are on screen.
764
+ *
765
+ * ```tsx
766
+ * <Virtualizer layout={listLayout({ rowHeight: 32 })}>
767
+ * <ListBox label="Cities" items={cities()} style={{ height: "300px", overflow: "auto" }}>
768
+ * {(city) => <Option>{city.name}</Option>}
769
+ * </ListBox>
770
+ * </Virtualizer>
771
+ * ```
772
+ *
773
+ * The collection inside keeps its whole collection — the state, the selection
774
+ * and the keyboard delegate all see every item. Only the DOM is a window.
775
+ */
776
+ export function Virtualizer(props: Incoming<VirtualizerComponentProps>) {
777
+ // Boxed: a signal holding a FUNCTION would call it, and both of these are
778
+ // functions that must be stored rather than read.
779
+ //
780
+ // `ownedWrite` because the collection attaches from its own component body,
781
+ // which is the only place it knows what to hand over.
782
+ const ATTACHED = { ownedWrite: true } as const;
783
+ const [collection, setCollection] = createSignal<{ read: Accessor<Collection<unknown>> }>(
784
+ { read: () => new ListCollection<unknown>([]) },
785
+ ATTACHED,
786
+ );
787
+ const [scrollRef, setScrollRef] = createSignal<{ ref: ElementRef } | null>(null, ATTACHED);
788
+ const [focusedKey, setFocusedKey] = createSignal<{ read: Accessor<Key | null> }>(
789
+ { read: () => null },
790
+ ATTACHED,
791
+ );
792
+ const [kept, setKept] = createSignal<{ read: Accessor<Iterable<Key>> }>(
793
+ { read: () => [] },
794
+ ATTACHED,
795
+ );
796
+ const layout = props.layout();
797
+
798
+ const state = virtualizer({
799
+ layout,
800
+ collection: () => collection().read(),
801
+ ref: () => {
802
+ const held = scrollRef();
803
+ return held === null ? null : access(held.ref);
804
+ },
805
+ overscan: () => props.overscan?.(),
806
+ // The FOCUSED row is persisted whatever the caller asked for: unmounting
807
+ // the element that holds focus drops focus to the body, and a keyboard
808
+ // user scrolling with the arrows would lose their place every time.
809
+ persistedKeys: () => {
810
+ const focused = focusedKey().read();
811
+ const given = [...(props.persistedKeys?.() ?? []), ...kept().read()];
812
+ return focused === null ? given : [...given, focused];
813
+ },
814
+ });
815
+
816
+ const value: VirtualizerValue = {
817
+ layout,
818
+ attach: (source, ref, focused, persisted) => {
819
+ setCollection({ read: source });
820
+ setScrollRef({ ref });
821
+ setFocusedKey({ read: focused });
822
+ if (persisted !== undefined) setKept({ read: persisted });
823
+ },
824
+ visible: state.visible,
825
+ contentSize: state.contentSize,
826
+ measure: state.measure,
827
+ shouldMeasure: () => state.visible().some((info) => info.isEstimated),
828
+ };
829
+
830
+ // `provide`, not `install`: two virtualised lists side by side both run
831
+ // their bodies before either one's children are built.
832
+ return provide(
833
+ VirtualizerContext,
834
+ () => value,
835
+ () => props.children as unknown,
836
+ );
837
+ }