@barqjs/virtual 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.
- package/LICENSE +21 -0
- package/README.md +177 -2
- package/dist/index.d.ts +6 -0
- package/dist/index.js +97 -0
- package/package.json +70 -4
- package/src/index.ts +207 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Salama Ashoush
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,178 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @barqjs/virtual
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Virtualized scrolling for barq. A list of ten thousand rows puts only the ones
|
|
4
|
+
in view in the DOM, and scrolling changes which ones. `createVirtualizer` and
|
|
5
|
+
`createWindowVirtualizer` run on `@tanstack/virtual-core`, the engine of
|
|
6
|
+
[TanStack Virtual](https://tanstack.com/virtual), and the API follows
|
|
7
|
+
`@tanstack/solid-virtual` with the differences listed below.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
```bash
|
|
12
|
+
bun add @barqjs/virtual
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
`@barqjs/core` and `@barqjs/web` are peer dependencies. `@tanstack/virtual-core` is a dependency of
|
|
16
|
+
this package and is re-exported from it, so one import covers the adapter and
|
|
17
|
+
the core.
|
|
18
|
+
|
|
19
|
+
## Example
|
|
20
|
+
|
|
21
|
+
A list of 10,000 rows of unknown height. Only the rows in the viewport, plus the
|
|
22
|
+
overscan, are in the document.
|
|
23
|
+
|
|
24
|
+
```tsx
|
|
25
|
+
import { For } from "@barqjs/core";
|
|
26
|
+
import { render } from "@barqjs/web";
|
|
27
|
+
import { type VirtualItem, createVirtualizer } from "@barqjs/virtual";
|
|
28
|
+
|
|
29
|
+
const contacts = Array.from({ length: 10_000 }, (_, id) => ({
|
|
30
|
+
id,
|
|
31
|
+
name: `salama ${id}`,
|
|
32
|
+
email: `salama+${id}@example.com`,
|
|
33
|
+
}));
|
|
34
|
+
|
|
35
|
+
function Contacts() {
|
|
36
|
+
let scroller: HTMLDivElement | null = null;
|
|
37
|
+
|
|
38
|
+
const virtualizer = createVirtualizer<HTMLDivElement, HTMLDivElement>(() => ({
|
|
39
|
+
count: contacts.length,
|
|
40
|
+
getScrollElement: () => scroller,
|
|
41
|
+
estimateSize: () => 48,
|
|
42
|
+
getItemKey: (index) => contacts[index].id,
|
|
43
|
+
overscan: 5,
|
|
44
|
+
}));
|
|
45
|
+
|
|
46
|
+
return (
|
|
47
|
+
<>
|
|
48
|
+
<button type="button" onClick={() => virtualizer.scrollToIndex(5000, { align: "center" })}>
|
|
49
|
+
Jump to the middle
|
|
50
|
+
</button>
|
|
51
|
+
<div
|
|
52
|
+
ref={(el: HTMLDivElement) => (scroller = el)}
|
|
53
|
+
style={{ height: "400px", overflow: "auto" }}
|
|
54
|
+
>
|
|
55
|
+
<div style={{ height: `${virtualizer.getTotalSize()}px`, position: "relative" }}>
|
|
56
|
+
<For each={virtualizer.getVirtualItems()} keyed={(item: VirtualItem) => item.key}>
|
|
57
|
+
{(item: () => VirtualItem) => (
|
|
58
|
+
<div
|
|
59
|
+
data-index={item().index}
|
|
60
|
+
ref={virtualizer.measureElement}
|
|
61
|
+
style={{
|
|
62
|
+
position: "absolute",
|
|
63
|
+
top: 0,
|
|
64
|
+
left: 0,
|
|
65
|
+
width: "100%",
|
|
66
|
+
transform: `translateY(${item().start}px)`,
|
|
67
|
+
}}
|
|
68
|
+
>
|
|
69
|
+
{contacts[item().index].name} ({contacts[item().index].email})
|
|
70
|
+
</div>
|
|
71
|
+
)}
|
|
72
|
+
</For>
|
|
73
|
+
</div>
|
|
74
|
+
</div>
|
|
75
|
+
</>
|
|
76
|
+
);
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
render(() => <Contacts />, document.body);
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Three things in it are barq, not TanStack:
|
|
83
|
+
|
|
84
|
+
- Options are an accessor. A signal read inside it (`count: rows().length`)
|
|
85
|
+
re-applies the options when it changes. A plain object works too, and so does
|
|
86
|
+
an object of getters.
|
|
87
|
+
- `For` takes a key function, `keyed={(item) => item.key}`, which hands the row
|
|
88
|
+
an accessor. `item().start` is then a tracked read, and a measurement moves
|
|
89
|
+
the rows already rendered. The items are a store reconciled by key, so a
|
|
90
|
+
by-item `For` reading `item.start` keeps its rows and moves them too, but the
|
|
91
|
+
compiler cannot see where the items come from and reports `BARQ004` for it.
|
|
92
|
+
- `ref={virtualizer.measureElement}` is enough for dynamic sizes. A barq ref
|
|
93
|
+
runs before its element is in the document, so the adapter measures on the
|
|
94
|
+
next microtask.
|
|
95
|
+
|
|
96
|
+
## API
|
|
97
|
+
|
|
98
|
+
- `createVirtualizer(options)`: an element scrolls. `count`, `getScrollElement`
|
|
99
|
+
and `estimateSize` are required; `observeElementRect`, `observeElementOffset`
|
|
100
|
+
and `scrollToFn` default to the core's element implementations.
|
|
101
|
+
- `createWindowVirtualizer(options)`: the window scrolls. `getScrollElement`
|
|
102
|
+
defaults to `window` and `initialOffset` to `window.scrollY`.
|
|
103
|
+
- `CreateVirtualizerOptions`, `CreateWindowVirtualizerOptions`: the option types
|
|
104
|
+
of the two functions.
|
|
105
|
+
- Everything `@tanstack/virtual-core` exports: `Virtualizer`, `VirtualItem`,
|
|
106
|
+
`VirtualizerOptions`, `Range`, `defaultRangeExtractor`, `defaultKeyExtractor`,
|
|
107
|
+
`measureElement`, `elementScroll`, `windowScroll`, `observeElementRect`,
|
|
108
|
+
`observeElementOffset`, `observeWindowRect`, `observeWindowOffset` and the
|
|
109
|
+
rest.
|
|
110
|
+
|
|
111
|
+
Both functions return the core's `Virtualizer`, so every option and method in
|
|
112
|
+
the [TanStack Virtual API](https://tanstack.com/virtual/latest/docs/api/virtualizer)
|
|
113
|
+
applies: `lanes`, `gap`, `paddingStart`, `paddingEnd`, `scrollMargin`,
|
|
114
|
+
`horizontal`, `overscan`, `rangeExtractor`, `anchorTo`, `enabled`,
|
|
115
|
+
`scrollToIndex`, `scrollToOffset`, `scrollBy`, `scrollToEnd`, `measure`,
|
|
116
|
+
`resizeItem`.
|
|
117
|
+
|
|
118
|
+
## What is reactive
|
|
119
|
+
|
|
120
|
+
The core owns its state. The adapter mirrors four reads into barq's graph and
|
|
121
|
+
passes everything else straight through.
|
|
122
|
+
|
|
123
|
+
- `getVirtualItems()` returns a store, reconciled by item key. A row keeps its
|
|
124
|
+
identity while its item stays in the window, and each field is its own
|
|
125
|
+
dependency.
|
|
126
|
+
- `getTotalSize()`, `isScrolling` and `range` are tracked when read inside a
|
|
127
|
+
tracking scope, and read the core directly anywhere else. An event handler
|
|
128
|
+
that calls `resizeItem` and then `getTotalSize()` sees the new total without
|
|
129
|
+
a `flush()`.
|
|
130
|
+
- `getVirtualItems()` is the rendered snapshot everywhere. After an imperative
|
|
131
|
+
write, call `flush()` before reading it, or read `getVirtualIndexes()`.
|
|
132
|
+
- `scrollOffset`, `scrollDirection`, `scrollRect`, `options` and the caches are
|
|
133
|
+
the core's own fields and are not tracked. The core only notifies when the
|
|
134
|
+
range or `isScrolling` changes, so a mirror of them would be stale between
|
|
135
|
+
notifications.
|
|
136
|
+
|
|
137
|
+
`isScrolling` and `range` are fields. The compiler wraps a member read in JSX,
|
|
138
|
+
so they render reactively as they are written:
|
|
139
|
+
|
|
140
|
+
```tsx
|
|
141
|
+
<div class={virtualizer.isScrolling ? "list scrolling" : "list"} />
|
|
142
|
+
```
|
|
143
|
+
|
|
144
|
+
## Server rendering
|
|
145
|
+
|
|
146
|
+
Nothing touches `window` or `document` at import or during a server render. On
|
|
147
|
+
the server the virtualizer never attaches to a scroll element, so it renders the
|
|
148
|
+
window that `initialRect` and `initialOffset` describe:
|
|
149
|
+
|
|
150
|
+
```tsx
|
|
151
|
+
createVirtualizer(() => ({
|
|
152
|
+
count: 1000,
|
|
153
|
+
getScrollElement: () => scroller,
|
|
154
|
+
estimateSize: () => 48,
|
|
155
|
+
initialRect: { width: 0, height: 600 },
|
|
156
|
+
}));
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
## Differences from the Solid adapter
|
|
160
|
+
|
|
161
|
+
- Options may be an accessor, which is how barq passes reactive options.
|
|
162
|
+
Solid's object of getters is still accepted.
|
|
163
|
+
- The mirrored items are reconciled by `key`, not by `index`. With a custom
|
|
164
|
+
`getItemKey` a row follows its item through a prepend instead of being
|
|
165
|
+
rewritten in place.
|
|
166
|
+
- `isScrolling` and `range` are reactive. The Solid adapter leaves them as plain
|
|
167
|
+
fields.
|
|
168
|
+
- `measureElement` defers to a microtask for an element that is not in the
|
|
169
|
+
document yet. With the Solid adapter the caller writes that `queueMicrotask`.
|
|
170
|
+
- `_willUpdate` runs in an effect after the rows are written, where the Solid
|
|
171
|
+
adapter calls it inside `onChange` before they are. The core uses it to sync
|
|
172
|
+
the scroll position after a prepend, and that write is clamped if the sizer
|
|
173
|
+
has not grown yet.
|
|
174
|
+
- An option set to `undefined` keeps the adapter's default.
|
|
175
|
+
|
|
176
|
+
The React adapter's `useFlushSync`, `directDomUpdates` and `containerRef` are
|
|
177
|
+
not ported. A barq write is flushed in a microtask, before the browser paints,
|
|
178
|
+
and a scroll already updates only the fields that changed.
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
import { PartialKeys, Virtualizer, VirtualizerOptions } from "@tanstack/virtual-core";
|
|
2
|
+
export * from "@tanstack/virtual-core";
|
|
3
|
+
export type CreateVirtualizerOptions<TScrollElement extends Element, TItemElement extends Element> = PartialKeys<VirtualizerOptions<TScrollElement, TItemElement>, "observeElementRect" | "observeElementOffset" | "scrollToFn">;
|
|
4
|
+
export type CreateWindowVirtualizerOptions<TItemElement extends Element> = PartialKeys<VirtualizerOptions<Window, TItemElement>, "getScrollElement" | "observeElementRect" | "observeElementOffset" | "scrollToFn">;
|
|
5
|
+
export declare function createVirtualizer<TScrollElement extends Element, TItemElement extends Element>(options: CreateVirtualizerOptions<TScrollElement, TItemElement> | (() => CreateVirtualizerOptions<TScrollElement, TItemElement>)): Virtualizer<TScrollElement, TItemElement>;
|
|
6
|
+
export declare function createWindowVirtualizer<TItemElement extends Element>(options: CreateWindowVirtualizerOptions<TItemElement> | (() => CreateWindowVirtualizerOptions<TItemElement>)): Virtualizer<Window, TItemElement>;
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
import { createEffect, createMemo, createProjection, createRenderEffect, createSignal, getObserver, onSettled, untrack } from "@barqjs/core";
|
|
2
|
+
import { isServer } from "@barqjs/web";
|
|
3
|
+
import { Virtualizer, elementScroll, observeElementOffset, observeElementRect, observeWindowOffset, observeWindowRect, windowScroll } from "@tanstack/virtual-core";
|
|
4
|
+
export * from "@tanstack/virtual-core";
|
|
5
|
+
// src/index.ts
|
|
6
|
+
function sameRange(a, b) {
|
|
7
|
+
return a?.startIndex === b?.startIndex && a?.endIndex === b?.endIndex;
|
|
8
|
+
}
|
|
9
|
+
function withDefaults(defaults, options) {
|
|
10
|
+
const merged = { ...defaults };
|
|
11
|
+
for (const [key, value] of Object.entries(options)) if (value !== void 0) merged[key] = value;
|
|
12
|
+
return merged;
|
|
13
|
+
}
|
|
14
|
+
function createVirtualizerBase(options) {
|
|
15
|
+
const [version, setVersion] = createSignal(0, { ownedWrite: true });
|
|
16
|
+
let published = 0;
|
|
17
|
+
const publish = () => {
|
|
18
|
+
setVersion(++published);
|
|
19
|
+
};
|
|
20
|
+
const resolve = () => {
|
|
21
|
+
const current = options();
|
|
22
|
+
current.getScrollElement();
|
|
23
|
+
return {
|
|
24
|
+
...current,
|
|
25
|
+
onChange: (instance, sync) => {
|
|
26
|
+
publish();
|
|
27
|
+
current.onChange?.(instance, sync);
|
|
28
|
+
}
|
|
29
|
+
};
|
|
30
|
+
};
|
|
31
|
+
const instance = new Virtualizer(untrack(resolve));
|
|
32
|
+
const mirror = (read) => () => {
|
|
33
|
+
version();
|
|
34
|
+
return untrack(read);
|
|
35
|
+
};
|
|
36
|
+
const virtualItems = createProjection(mirror(() => instance.getVirtualItems()), [], { key: "key" });
|
|
37
|
+
const totalSize = createMemo(mirror(() => instance.getTotalSize()));
|
|
38
|
+
const isScrolling = createMemo(mirror(() => instance.isScrolling));
|
|
39
|
+
const range = createMemo(mirror(() => instance.calculateRange()), { equals: sameRange });
|
|
40
|
+
const getVirtualItems = () => virtualItems;
|
|
41
|
+
const getTotalSize = () => getObserver() === null ? instance.getTotalSize() : totalSize();
|
|
42
|
+
const measureElement = (node) => {
|
|
43
|
+
if (node === null || node.isConnected) {
|
|
44
|
+
instance.measureElement(node);
|
|
45
|
+
return;
|
|
46
|
+
}
|
|
47
|
+
queueMicrotask(() => {
|
|
48
|
+
if (node.isConnected) instance.measureElement(node);
|
|
49
|
+
});
|
|
50
|
+
};
|
|
51
|
+
const virtualizer = new Proxy(instance, { get(target, property) {
|
|
52
|
+
switch (property) {
|
|
53
|
+
case "getVirtualItems": return getVirtualItems;
|
|
54
|
+
case "getTotalSize": return getTotalSize;
|
|
55
|
+
case "measureElement": return measureElement;
|
|
56
|
+
case "isScrolling": return getObserver() === null ? target.isScrolling : isScrolling();
|
|
57
|
+
case "range": return getObserver() === null ? target.range : range();
|
|
58
|
+
default: return Reflect.get(target, property);
|
|
59
|
+
}
|
|
60
|
+
} });
|
|
61
|
+
if (isServer) return virtualizer;
|
|
62
|
+
createRenderEffect(resolve, (resolved) => {
|
|
63
|
+
untrack(() => instance.setOptions(resolved));
|
|
64
|
+
publish();
|
|
65
|
+
});
|
|
66
|
+
let mounted = false;
|
|
67
|
+
onSettled(() => {
|
|
68
|
+
const unmount = instance._didMount();
|
|
69
|
+
mounted = true;
|
|
70
|
+
untrack(instance._willUpdate);
|
|
71
|
+
return () => {
|
|
72
|
+
mounted = false;
|
|
73
|
+
unmount();
|
|
74
|
+
};
|
|
75
|
+
});
|
|
76
|
+
createEffect(version, () => {
|
|
77
|
+
if (mounted) untrack(instance._willUpdate);
|
|
78
|
+
});
|
|
79
|
+
return virtualizer;
|
|
80
|
+
}
|
|
81
|
+
function createVirtualizer(options) {
|
|
82
|
+
return createVirtualizerBase(() => withDefaults({
|
|
83
|
+
observeElementRect,
|
|
84
|
+
observeElementOffset,
|
|
85
|
+
scrollToFn: elementScroll
|
|
86
|
+
}, typeof options === "function" ? options() : options));
|
|
87
|
+
}
|
|
88
|
+
function createWindowVirtualizer(options) {
|
|
89
|
+
return createVirtualizerBase(() => withDefaults({
|
|
90
|
+
getScrollElement: () => isServer ? null : window,
|
|
91
|
+
observeElementRect: observeWindowRect,
|
|
92
|
+
observeElementOffset: observeWindowOffset,
|
|
93
|
+
scrollToFn: windowScroll,
|
|
94
|
+
initialOffset: () => isServer ? 0 : window.scrollY
|
|
95
|
+
}, typeof options === "function" ? options() : options));
|
|
96
|
+
}
|
|
97
|
+
export { createVirtualizer, createWindowVirtualizer };
|
package/package.json
CHANGED
|
@@ -1,6 +1,72 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@barqjs/virtual",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.2.0-next.1",
|
|
4
|
+
"description": "Virtualized scrolling for barq: createVirtualizer and createWindowVirtualizer, on @tanstack/virtual-core",
|
|
5
|
+
"keywords": [
|
|
6
|
+
"barq",
|
|
7
|
+
"headless",
|
|
8
|
+
"tanstack",
|
|
9
|
+
"virtual",
|
|
10
|
+
"virtualization"
|
|
11
|
+
],
|
|
12
|
+
"homepage": "https://github.com/salamaashoush/barq#readme",
|
|
13
|
+
"bugs": {
|
|
14
|
+
"url": "https://github.com/salamaashoush/barq/issues"
|
|
15
|
+
},
|
|
16
|
+
"license": "MIT",
|
|
17
|
+
"repository": {
|
|
18
|
+
"type": "git",
|
|
19
|
+
"url": "git+https://github.com/salamaashoush/barq.git",
|
|
20
|
+
"directory": "packages/virtual"
|
|
21
|
+
},
|
|
22
|
+
"files": [
|
|
23
|
+
"dist",
|
|
24
|
+
"src",
|
|
25
|
+
"!src/**/*.test.ts",
|
|
26
|
+
"!src/**/*.test.tsx",
|
|
27
|
+
"!src/**/test-*.ts",
|
|
28
|
+
"!src/**/*-harness.ts",
|
|
29
|
+
"!src/**/*-probe.ts",
|
|
30
|
+
"!src/**/fixtures",
|
|
31
|
+
"!src/**/fixtures.ts",
|
|
32
|
+
"!src/**/ssr-fixtures.ts"
|
|
33
|
+
],
|
|
34
|
+
"type": "module",
|
|
35
|
+
"sideEffects": false,
|
|
36
|
+
"main": "./dist/index.js",
|
|
37
|
+
"types": "./dist/index.d.ts",
|
|
38
|
+
"exports": {
|
|
39
|
+
".": {
|
|
40
|
+
"types": "./dist/index.d.ts",
|
|
41
|
+
"bun": "./src/index.ts",
|
|
42
|
+
"import": "./dist/index.js"
|
|
43
|
+
}
|
|
44
|
+
},
|
|
45
|
+
"publishConfig": {
|
|
46
|
+
"access": "public",
|
|
47
|
+
"provenance": true
|
|
48
|
+
},
|
|
49
|
+
"scripts": {
|
|
50
|
+
"build": "tsdown",
|
|
51
|
+
"dev": "tsdown --watch",
|
|
52
|
+
"test": "bun test --timeout 10000 && bun test --timeout 10000 --conditions=development",
|
|
53
|
+
"typecheck": "tsc --noEmit"
|
|
54
|
+
},
|
|
55
|
+
"dependencies": {
|
|
56
|
+
"@tanstack/virtual-core": "^3.19.11"
|
|
57
|
+
},
|
|
58
|
+
"devDependencies": {
|
|
59
|
+
"@barqjs/compiler": "0.2.0-next.1",
|
|
60
|
+
"@barqjs/core": "0.2.0-next.1",
|
|
61
|
+
"@barqjs/server": "0.2.0-next.1",
|
|
62
|
+
"@barqjs/vite": "0.2.0-next.1",
|
|
63
|
+
"@barqjs/web": "0.2.0-next.1",
|
|
64
|
+
"@happy-dom/global-registrator": "^21.0.4",
|
|
65
|
+
"@types/bun": "^1.4.4",
|
|
66
|
+
"typescript": "^7.0.2"
|
|
67
|
+
},
|
|
68
|
+
"peerDependencies": {
|
|
69
|
+
"@barqjs/core": ">=0.2.0-next.1",
|
|
70
|
+
"@barqjs/web": ">=0.2.0-next.1"
|
|
71
|
+
}
|
|
72
|
+
}
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,207 @@
|
|
|
1
|
+
import {
|
|
2
|
+
createEffect,
|
|
3
|
+
createMemo,
|
|
4
|
+
createProjection,
|
|
5
|
+
createRenderEffect,
|
|
6
|
+
createSignal,
|
|
7
|
+
getObserver,
|
|
8
|
+
onSettled,
|
|
9
|
+
untrack,
|
|
10
|
+
} from "@barqjs/core";
|
|
11
|
+
import { isServer } from "@barqjs/web";
|
|
12
|
+
import {
|
|
13
|
+
type PartialKeys,
|
|
14
|
+
type VirtualItem,
|
|
15
|
+
type VirtualizerOptions,
|
|
16
|
+
Virtualizer,
|
|
17
|
+
elementScroll,
|
|
18
|
+
observeElementOffset,
|
|
19
|
+
observeElementRect,
|
|
20
|
+
observeWindowOffset,
|
|
21
|
+
observeWindowRect,
|
|
22
|
+
windowScroll,
|
|
23
|
+
} from "@tanstack/virtual-core";
|
|
24
|
+
|
|
25
|
+
export * from "@tanstack/virtual-core";
|
|
26
|
+
|
|
27
|
+
export type CreateVirtualizerOptions<
|
|
28
|
+
TScrollElement extends Element,
|
|
29
|
+
TItemElement extends Element,
|
|
30
|
+
> = PartialKeys<
|
|
31
|
+
VirtualizerOptions<TScrollElement, TItemElement>,
|
|
32
|
+
"observeElementRect" | "observeElementOffset" | "scrollToFn"
|
|
33
|
+
>;
|
|
34
|
+
|
|
35
|
+
export type CreateWindowVirtualizerOptions<TItemElement extends Element> = PartialKeys<
|
|
36
|
+
VirtualizerOptions<Window, TItemElement>,
|
|
37
|
+
"getScrollElement" | "observeElementRect" | "observeElementOffset" | "scrollToFn"
|
|
38
|
+
>;
|
|
39
|
+
|
|
40
|
+
type Range = Virtualizer<Element, Element>["range"];
|
|
41
|
+
|
|
42
|
+
function sameRange(a: Range, b: Range): boolean {
|
|
43
|
+
return a?.startIndex === b?.startIndex && a?.endIndex === b?.endIndex;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
// A key the caller leaves `undefined` keeps the adapter's default, so a
|
|
47
|
+
// conditional `scrollToFn: custom ? fn : undefined` cannot erase a required one.
|
|
48
|
+
function withDefaults<TOptions extends object>(
|
|
49
|
+
defaults: Partial<TOptions>,
|
|
50
|
+
options: object,
|
|
51
|
+
): TOptions {
|
|
52
|
+
const merged: Record<string, unknown> = { ...defaults };
|
|
53
|
+
for (const [key, value] of Object.entries(options)) {
|
|
54
|
+
if (value !== undefined) merged[key] = value;
|
|
55
|
+
}
|
|
56
|
+
return merged as TOptions;
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
function createVirtualizerBase<
|
|
60
|
+
TScrollElement extends Element | Window,
|
|
61
|
+
TItemElement extends Element,
|
|
62
|
+
>(
|
|
63
|
+
options: () => VirtualizerOptions<TScrollElement, TItemElement>,
|
|
64
|
+
): Virtualizer<TScrollElement, TItemElement> {
|
|
65
|
+
// The core writes its own state and reads it back in the same tick, and a
|
|
66
|
+
// signal write is not published until the flush. So the core keeps the
|
|
67
|
+
// state, and this signal only says "read it again".
|
|
68
|
+
const [version, setVersion] = createSignal(0, { ownedWrite: true });
|
|
69
|
+
let published = 0;
|
|
70
|
+
const publish = (): void => {
|
|
71
|
+
setVersion(++published);
|
|
72
|
+
};
|
|
73
|
+
|
|
74
|
+
const resolve = (): VirtualizerOptions<TScrollElement, TItemElement> => {
|
|
75
|
+
const current = options();
|
|
76
|
+
// Read here so a scroll element held in a signal re-applies the options
|
|
77
|
+
// when it changes.
|
|
78
|
+
current.getScrollElement();
|
|
79
|
+
return {
|
|
80
|
+
...current,
|
|
81
|
+
onChange: (instance, sync) => {
|
|
82
|
+
publish();
|
|
83
|
+
current.onChange?.(instance, sync);
|
|
84
|
+
},
|
|
85
|
+
};
|
|
86
|
+
};
|
|
87
|
+
|
|
88
|
+
const instance = new Virtualizer<TScrollElement, TItemElement>(untrack(resolve));
|
|
89
|
+
|
|
90
|
+
// The core calls the caller's `estimateSize` and `getItemKey`, which may read
|
|
91
|
+
// signals. Those reads are not dependencies of the mirror: `version` alone
|
|
92
|
+
// says when the core has something new.
|
|
93
|
+
const mirror =
|
|
94
|
+
<T>(read: () => T) =>
|
|
95
|
+
(): T => {
|
|
96
|
+
version();
|
|
97
|
+
return untrack(read);
|
|
98
|
+
};
|
|
99
|
+
const virtualItems = createProjection<Array<VirtualItem>>(
|
|
100
|
+
mirror(() => instance.getVirtualItems()),
|
|
101
|
+
[],
|
|
102
|
+
{ key: "key" },
|
|
103
|
+
);
|
|
104
|
+
const totalSize = createMemo(mirror(() => instance.getTotalSize()));
|
|
105
|
+
const isScrolling = createMemo(mirror(() => instance.isScrolling));
|
|
106
|
+
const range = createMemo(
|
|
107
|
+
mirror(() => instance.calculateRange()),
|
|
108
|
+
{ equals: sameRange },
|
|
109
|
+
);
|
|
110
|
+
|
|
111
|
+
const getVirtualItems = (): Array<VirtualItem> => virtualItems;
|
|
112
|
+
const getTotalSize = (): number =>
|
|
113
|
+
getObserver() === null ? instance.getTotalSize() : totalSize();
|
|
114
|
+
|
|
115
|
+
// A ref runs while its element is being built, before it is in the document,
|
|
116
|
+
// where it has no layout and its attributes may not be written yet.
|
|
117
|
+
const measureElement = (node: TItemElement | null): void => {
|
|
118
|
+
if (node === null || node.isConnected) {
|
|
119
|
+
instance.measureElement(node);
|
|
120
|
+
return;
|
|
121
|
+
}
|
|
122
|
+
queueMicrotask(() => {
|
|
123
|
+
if (node.isConnected) instance.measureElement(node);
|
|
124
|
+
});
|
|
125
|
+
};
|
|
126
|
+
|
|
127
|
+
const virtualizer = new Proxy(instance, {
|
|
128
|
+
get(target, property) {
|
|
129
|
+
switch (property) {
|
|
130
|
+
case "getVirtualItems":
|
|
131
|
+
return getVirtualItems;
|
|
132
|
+
case "getTotalSize":
|
|
133
|
+
return getTotalSize;
|
|
134
|
+
case "measureElement":
|
|
135
|
+
return measureElement;
|
|
136
|
+
case "isScrolling":
|
|
137
|
+
return getObserver() === null ? target.isScrolling : isScrolling();
|
|
138
|
+
case "range":
|
|
139
|
+
return getObserver() === null ? target.range : range();
|
|
140
|
+
default:
|
|
141
|
+
return Reflect.get(target, property);
|
|
142
|
+
}
|
|
143
|
+
},
|
|
144
|
+
});
|
|
145
|
+
|
|
146
|
+
if (isServer) return virtualizer;
|
|
147
|
+
|
|
148
|
+
createRenderEffect(resolve, (resolved) => {
|
|
149
|
+
untrack(() => instance.setOptions(resolved));
|
|
150
|
+
publish();
|
|
151
|
+
});
|
|
152
|
+
|
|
153
|
+
let mounted = false;
|
|
154
|
+
onSettled(() => {
|
|
155
|
+
const unmount = instance._didMount();
|
|
156
|
+
mounted = true;
|
|
157
|
+
untrack(instance._willUpdate);
|
|
158
|
+
return () => {
|
|
159
|
+
mounted = false;
|
|
160
|
+
unmount();
|
|
161
|
+
};
|
|
162
|
+
});
|
|
163
|
+
|
|
164
|
+
// After the rows and the sizer have been written: the core syncs the scroll
|
|
165
|
+
// position to a layout it expects the document to already have.
|
|
166
|
+
createEffect(version, () => {
|
|
167
|
+
if (mounted) untrack(instance._willUpdate);
|
|
168
|
+
});
|
|
169
|
+
|
|
170
|
+
return virtualizer;
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
export function createVirtualizer<TScrollElement extends Element, TItemElement extends Element>(
|
|
174
|
+
options:
|
|
175
|
+
| CreateVirtualizerOptions<TScrollElement, TItemElement>
|
|
176
|
+
| (() => CreateVirtualizerOptions<TScrollElement, TItemElement>),
|
|
177
|
+
): Virtualizer<TScrollElement, TItemElement> {
|
|
178
|
+
return createVirtualizerBase<TScrollElement, TItemElement>(() =>
|
|
179
|
+
withDefaults<VirtualizerOptions<TScrollElement, TItemElement>>(
|
|
180
|
+
{
|
|
181
|
+
observeElementRect,
|
|
182
|
+
observeElementOffset,
|
|
183
|
+
scrollToFn: elementScroll,
|
|
184
|
+
},
|
|
185
|
+
typeof options === "function" ? options() : options,
|
|
186
|
+
),
|
|
187
|
+
);
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
export function createWindowVirtualizer<TItemElement extends Element>(
|
|
191
|
+
options:
|
|
192
|
+
| CreateWindowVirtualizerOptions<TItemElement>
|
|
193
|
+
| (() => CreateWindowVirtualizerOptions<TItemElement>),
|
|
194
|
+
): Virtualizer<Window, TItemElement> {
|
|
195
|
+
return createVirtualizerBase<Window, TItemElement>(() =>
|
|
196
|
+
withDefaults<VirtualizerOptions<Window, TItemElement>>(
|
|
197
|
+
{
|
|
198
|
+
getScrollElement: () => (isServer ? null : window),
|
|
199
|
+
observeElementRect: observeWindowRect,
|
|
200
|
+
observeElementOffset: observeWindowOffset,
|
|
201
|
+
scrollToFn: windowScroll,
|
|
202
|
+
initialOffset: () => (isServer ? 0 : window.scrollY),
|
|
203
|
+
},
|
|
204
|
+
typeof options === "function" ? options() : options,
|
|
205
|
+
),
|
|
206
|
+
);
|
|
207
|
+
}
|