@octanejs/tanstack-virtual 0.1.49 → 0.1.50

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.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2021-present Tanner Linsley
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/UPSTREAM.md ADDED
@@ -0,0 +1,60 @@
1
+ # Upstream
2
+
3
+ - Repository: https://github.com/TanStack/virtual
4
+ - Package: `@tanstack/react-virtual@3.14.12`
5
+ - Release commit: `df47889fc87af0b5ff46a9805820f60cff6828ff`
6
+ - Source root: `packages/react-virtual/src`
7
+ - Test roots: `packages/react-virtual/tests` and `packages/react-virtual/e2e`
8
+ - License: MIT; exact root license in `LICENSE.upstream`
9
+ - npm artifact SHA-256: `61a7b5feaecaff7b44527675b24df7bb102ef09327b314e2f770e786b2a8412e`
10
+ - Runtime dependency: `@tanstack/virtual-core@3.17.10`, imported directly
11
+
12
+ ## Source boundary
13
+
14
+ `audit/upstream.lock.json` pins all 41 files in the upstream package, including
15
+ its complete source, unit tests and browser fixtures. The immutable source and
16
+ artifact are test inputs and are excluded from publication. The binding adapts
17
+ the React hook implementation; `src/internal.ts` supplies native slot handling.
18
+ The core's public implementation is consumed from its package.
19
+
20
+ The adapter grows the direct-DOM container before `_willUpdate` restores an
21
+ end-anchored scroll position. Otherwise the browser clamps a prepend's new scroll
22
+ offset against the old container height. Both positioning modes have a browser
23
+ regression with the old adapter as the failing control, the same current core,
24
+ and assertions on scroll extent, offset and retained row identity. Public hook
25
+ signatures also exclude the compiler's internal trailing slot argument.
26
+
27
+ ## Executable coverage
28
+
29
+ The exact release contains seven unit registrations and 35 browser registrations,
30
+ including expanded positioning-mode cases. `audit/registrations.json` and
31
+ `audit/crosswalk.json` account for all 42. `materialize run` regenerates the Octane
32
+ adaptation using only the mechanical rewrites in the lock. No upstream runtime
33
+ assertions are removed or relaxed.
34
+
35
+ | Suite | React | Octane |
36
+ | --- | --- | --- |
37
+ | Unit | Seven unchanged cases | Seven mechanically adapted cases |
38
+ | Chromium | All 35 unchanged browser cases | All 35 adapted cases plus two direct-DOM prepend regressions |
39
+ | Dedicated upstream type cases | None at this release | None to materialize |
40
+ | Authored strict public type probes | All 26 exports with negative controls | The same contracts and negative controls |
41
+
42
+ Browser coverage includes cached measurements while hidden, chat prepend/append
43
+ and streaming behavior, both direct-DOM positioning modes, dynamic measurement,
44
+ scroll anchoring, smooth scrolling and stale item keys. The pristine compiler
45
+ fixture runs Babel's React Compiler. Its native counterpart runs Octane's
46
+ compiler and checks the same visible rows, style positions and render-count
47
+ bounds; this is not a claim that React Compiler compiles Octane applications.
48
+ Vite and Rolldown use explicit compilation settings because the pinned monorepo
49
+ configuration extends files outside the copied package. Test inputs remain intact.
50
+
51
+ The browser wrapper checks every expanded test identity, zero skipped or failed
52
+ cases, the process exit status and the complete report. Required parity lanes
53
+ also execute the four existing React/Octane differential scenarios, native
54
+ conformance, strict type programs and SSR/hydration. Hydration uses a real server
55
+ compile and a separately compiled client tree, retains the existing rows and
56
+ button, updates the extent and verifies observer disposal.
57
+
58
+ The only retained runtime divergence is Octane's nested `flushSync` behavior,
59
+ recorded with its executable case in `audit/react-parity.json`. Browser render
60
+ counts are deterministic performance guards; no wall-clock speedup is claimed.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@octanejs/tanstack-virtual",
3
- "version": "0.1.49",
3
+ "version": "0.1.50",
4
4
  "license": "MIT",
5
5
  "type": "module",
6
6
  "engines": {
@@ -31,27 +31,40 @@
31
31
  "types": "src/index.ts",
32
32
  "files": [
33
33
  "src",
34
- "README.md"
34
+ "README.md",
35
+ "LICENSE.upstream",
36
+ "LICENSE",
37
+ "UPSTREAM.md"
35
38
  ],
36
39
  "exports": {
37
40
  ".": "./src/index.ts"
38
41
  },
39
42
  "dependencies": {
40
- "@tanstack/virtual-core": "3.17.3"
43
+ "@tanstack/virtual-core": "3.17.10"
41
44
  },
42
45
  "peerDependencies": {
43
46
  "octane": "^0.1.51 || ^0.2.0"
44
47
  },
45
48
  "devDependencies": {
46
- "@tanstack/react-virtual": "3.14.5",
47
- "@tsrx/react": "^0.2.63",
49
+ "@tanstack/react-virtual": "3.14.12",
50
+ "@tsrx/react": "^0.3.0",
48
51
  "esbuild": "^0.28.1",
49
- "react": "^19.2.7",
50
- "react-dom": "^19.2.7",
52
+ "react": "19.2.7",
53
+ "react-dom": "19.2.7",
51
54
  "vitest": "^4.1.10",
52
- "octane": "0.2.0"
55
+ "@testing-library/react": "^16.3.2",
56
+ "@testing-library/jest-dom": "^6.9.1",
57
+ "@babel/core": "7.29.7",
58
+ "babel-plugin-react-compiler": "1.0.0",
59
+ "@playwright/test": "^1.61.1",
60
+ "@types/react": "^19.2.17",
61
+ "@types/react-dom": "^19.2.3",
62
+ "resize-observer-polyfill": "1.5.1",
63
+ "vite": "^8.1.5",
64
+ "octane": "0.2.16",
65
+ "@octanejs/testing-library": "0.1.51"
53
66
  },
54
67
  "scripts": {
55
- "test": "vitest run"
68
+ "test": "vitest run --root ../.. --project tanstack-virtual --project tanstack-virtual-adapted --project tanstack-virtual-differential --project tanstack-virtual-ssr"
56
69
  }
57
70
  }
package/src/index.ts CHANGED
@@ -59,6 +59,8 @@ export type ReactVirtualizerOptions<
59
59
  * positions and the container size directly to the DOM, and only
60
60
  * re-renders when the visible index range or `isScrolling` changes. See
61
61
  * upstream @tanstack/react-virtual docs for the layout requirements.
62
+ * Set this flag and directDomUpdatesMode at mount; toggling either later
63
+ * can leave stale inline styles on the items and container.
62
64
  */
63
65
  directDomUpdates?: boolean;
64
66
  /** How `directDomUpdates` positions items: `'transform'` (default) or `'position'`. */
@@ -83,11 +85,7 @@ function useVirtualizerBase<TScrollElement extends Element | Window, TItemElemen
83
85
  directDomUpdates = false,
84
86
  directDomUpdatesMode = 'transform',
85
87
  ...options
86
- }: VirtualizerOptions<TScrollElement, TItemElement> & {
87
- useFlushSync?: boolean;
88
- directDomUpdates?: boolean;
89
- directDomUpdatesMode?: 'position' | 'transform';
90
- },
88
+ }: ReactVirtualizerOptions<TScrollElement, TItemElement>,
91
89
  slot: symbol | undefined,
92
90
  ): ReactVirtualizer<TScrollElement, TItemElement> {
93
91
  const rerender = useReducer<number, void, number>((x) => x + 1, 0, subSlot(slot, 'uvb:r'))[1];
@@ -106,7 +104,7 @@ function useVirtualizerBase<TScrollElement extends Element | Window, TItemElemen
106
104
  directRef.current.enabled = directDomUpdates;
107
105
  directRef.current.mode = directDomUpdatesMode;
108
106
 
109
- const applyDirectStyles = (instance: Virtualizer<TScrollElement, TItemElement>) => {
107
+ const applyContainerSize = (instance: Virtualizer<TScrollElement, TItemElement>) => {
110
108
  const state = directRef.current;
111
109
  if (!state.enabled || !state.container) return;
112
110
  const totalSize = instance.getTotalSize();
@@ -115,6 +113,12 @@ function useVirtualizerBase<TScrollElement extends Element | Window, TItemElemen
115
113
  const sizeAxis = instance.options.horizontal ? 'width' : 'height';
116
114
  state.container.style[sizeAxis] = `${totalSize}px`;
117
115
  }
116
+ };
117
+
118
+ const applyDirectStyles = (instance: Virtualizer<TScrollElement, TItemElement>) => {
119
+ const state = directRef.current;
120
+ if (!state.enabled || !state.container) return;
121
+ applyContainerSize(instance);
118
122
  const horizontal = !!instance.options.horizontal;
119
123
  const useTransform = state.mode === 'transform';
120
124
  const posAxis = horizontal ? 'left' : 'top';
@@ -196,7 +200,16 @@ function useVirtualizerBase<TScrollElement extends Element | Window, TItemElemen
196
200
  instance.setOptions(resolvedOptions);
197
201
 
198
202
  useIsomorphicLayoutEffect(() => instance._didMount(), [], subSlot(slot, 'uvb:m'));
199
- useIsomorphicLayoutEffect(() => instance._willUpdate(), undefined, subSlot(slot, 'uvb:w'));
203
+ useIsomorphicLayoutEffect(
204
+ () => {
205
+ // Grow the scroll extent before core synchronizes an end-anchored prepend;
206
+ // the browser otherwise clamps the new offset to the old container size.
207
+ applyContainerSize(instance);
208
+ return instance._willUpdate();
209
+ },
210
+ undefined,
211
+ subSlot(slot, 'uvb:w'),
212
+ );
200
213
  useIsomorphicLayoutEffect(
201
214
  () => {
202
215
  applyDirectStyles(instance);
@@ -222,6 +235,13 @@ function useIsomorphicLayoutEffect(
222
235
  }
223
236
  }
224
237
 
238
+ export function useVirtualizer<TScrollElement extends Element, TItemElement extends Element>(
239
+ options: PartialKeys<
240
+ ReactVirtualizerOptions<TScrollElement, TItemElement>,
241
+ 'observeElementRect' | 'observeElementOffset' | 'scrollToFn'
242
+ >,
243
+ ): ReactVirtualizer<TScrollElement, TItemElement>;
244
+
225
245
  export function useVirtualizer<TScrollElement extends Element, TItemElement extends Element>(
226
246
  options: PartialKeys<
227
247
  ReactVirtualizerOptions<TScrollElement, TItemElement>,
@@ -241,6 +261,13 @@ export function useVirtualizer<TScrollElement extends Element, TItemElement exte
241
261
  );
242
262
  }
243
263
 
264
+ export function useWindowVirtualizer<TItemElement extends Element>(
265
+ options: PartialKeys<
266
+ ReactVirtualizerOptions<Window, TItemElement>,
267
+ 'getScrollElement' | 'observeElementRect' | 'observeElementOffset' | 'scrollToFn'
268
+ >,
269
+ ): ReactVirtualizer<Window, TItemElement>;
270
+
244
271
  export function useWindowVirtualizer<TItemElement extends Element>(
245
272
  options: PartialKeys<
246
273
  ReactVirtualizerOptions<Window, TItemElement>,