Repository navigation
Release 3.1.0: headless useVirtualWindow, viewport reveal, scroll control - #1
Merged
Merged
Conversation
The windowing engine becomes a public hook. useVirtualWindow takes a count
and an estimated size and returns the items to render with their offsets, a
ref for the scroll container, a per-item ref that measures rows and corrects
the offsets below them, totalSize for the sizer, and scrollToIndex /
scrollToOffset. It renders nothing and owns no styles, so it fits a table, a
grid, or a scroller that already exists. VirtualRenderWave is now built on it.
New on the component: revealMode "viewport", which reveals the rows inside
the rendered window rather than counting forward from startIndex, so a small
batchSize still fills the screen on a long list; initialScrollOffset and
initialScrollIndex, both read once, so the first paint and the server markup
already show that window; onRangeChange, called after commit whenever the
rendered or visible range moves. The handle's scrollTo now accepts
{ align, behavior } alongside the old behavior string.
The height cache is replaced by a keyed size cache, so a measured row keeps
its height across a reorder when getItemKey is set.
Fixes carried in the same change:
- React 18 could not attach a ref to a forwardRef outerElement or
innerElement, so the list could not scroll or measure. A dev-only
console.error now names a wrapper that swallows the ref.
- Package types did not resolve under Node16/NodeNext from either CJS or
ESM. The exports map carries a types entry per condition and the build
emits both .d.ts and .d.cts.
- onEndReached never fired when the content was shorter than the viewport.
- Programmatic scrolls near the end of a list of taller-than-estimated rows
stopped short of the target and never re-aimed.
- initialScrollIndex ignored scrollMargin on the first render.
- align "auto" oscillated on an item taller than the viewport.
- scrollToIndex(NaN), scrollToOffset(NaN) and a non-finite
initialScrollOffset reset the position to the top instead of being ignored.
- An itemHeight or estimateSize of 0, NaN or Infinity mounted every row, and
a negative or NaN overscan rendered none.
- keyboardNavigation took the arrows, Home, End and the page keys from a
focused control inside a row.
- The fade-in ignored prefers-reduced-motion.
- The ref-swallowing warning fired twice under StrictMode.
WrapperProps.ref is now optional and typed RefObject<any>, and
WrapperComponent may return a promise. That is source-breaking for code
reading props.ref.current, and it is what makes a custom wrapper compile in
shapes other than a forwardRef typed for HTMLElement.
179 tests across 18 files. New suites for the size cache (including a property test against a brute-force prefix sum), the headless hook and its edge cases, the viewport reveal mode, server rendering, end detection, the component's scroll and feature surface, and the five natural shapes a custom outerElement or innerElement can take, which are checked by tsc as well as at runtime. test/regressions310.test.tsx holds one failing-before-the-fix case for each bug fixed in this release. test/setup.ts guards the scrollTo stub, since the SSR suites run in the node environment where there is no Element to patch.
…d 19 Node 20 and 22 against the pinned React 19 devDependencies, plus a job that reinstalls React 18 and runs typecheck and tests against it. That job earns its keep: a WrapperComponent return type that compiles under @types/react 19 fails under 18, and no React 19 check would have caught it.
The README gains a useVirtualWindow section with a worked example, full option and result tables, the four new component props, and a note on wrapping a custom outerElement in forwardRef for React 18. The changelog entry for 3.0.0 said 2026-07-28. Both the git tag and the npm publish record say 2026-08-22.
❌ Deploy Preview for astonishing-cuchufli-c17417 failed. Why did it fail? →
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Release 3.1.0: headless
useVirtualWindow, viewport reveal, scroll control3.1.0 exposes the windowing engine as a public hook and rebuilds
VirtualRenderWaveon top of it. Alongside the hook: four new component props, an options object on the handle'sscrollTo, eleven fixes with a regression test each, a CI workflow, and a test suite that grows from 42 tests to 179. Four commits; the full list is in the 3.1.0 section ofCHANGELOG.md.What is in it
useVirtualWindow. Given a count and an estimated size it returns the items to render with their offsets, a ref for the scroll container, a per-item ref that measures rows and corrects the offsets below them,totalSizefor the sizer, andscrollToIndex/scrollToOffset. It renders nothing and owns no styles, so it fits a table, a grid, or a scroller that already exists. The first render depends only on the count, the estimate, overscan,scrollMargin,getItemKeyand theinitial*options, so server markup and the first client render agree.Component props.
revealMode("sequential"is the 3.0 behaviour;"viewport"reveals the rows inside the rendered window, so a smallbatchSizestill fills the screen on a long list),initialScrollOffsetandinitialScrollIndex(read once, applied on the first paint and in server markup), andonRangeChange(fires after commit whenever the rendered or visible range moves).Handle.
scrollTo(index, { align, behavior }).alignis"start","center","end"or"auto". The old behavior-string form still works.Fixes. React 18 could not attach a ref to a
forwardRefwrapper; types did not resolve under Node16/NodeNext;onEndReachednever fired on content shorter than the viewport; programmatic scrolls near the end of a taller-than-estimated list stopped short;initialScrollIndexignoredscrollMargin;align: "auto"oscillated on an item taller than the viewport; NaN scroll targets reset to the top; degenerateitemHeightoroverscanmounted every row or none;keyboardNavigationstole keys from focused controls inside rows; the fade-in ignoredprefers-reduced-motion; the ref-swallowing warning fired twice under StrictMode. The height cache is replaced by a keyed size cache, so measured heights survive a reorder whengetItemKeyis set.CI.
.github/workflows/ci.ymlruns typecheck, tests, build and the package checks on Node 20 and 22, plus a job that reinstalls React 18 and runs typecheck and tests. That job already earns its place: aWrapperComponentreturn type that compiles under@types/react19 fails under 18.One type change that can break a compile
WrapperProps.refis now optional and typedRefObject<any>(it was a requiredRefObject<HTMLElement | null>). Code that readsprops.ref.currentneedsprops.ref?.current.The same change is what lets a custom
outerElementorinnerElementcompile in more than one shape. Before it, only aforwardRefcomponent typed forHTMLElementpassedtsc; aforwardReftyped forHTMLDivElement, a plainFC<WrapperProps>attaching the ref itself, anFCreadingprops.ref?.current, and (under@types/react19) anything typedFC<WrapperProps>were all rejected. All five shapes compile now, andtest/wrapperElements.test.tsxchecks them withtscas well as at runtime.Whether this belongs in 3.1.0 or forces 4.0.0 is a judgement call. The change is source-breaking for a narrow pattern that could only have been written in one specific way, and it unblocks the wrapper feature for everyone else. I have left it as 3.1.0; reviewer's call.
Verification
All of these were run on this branch, on the packed tarball where relevant.
tscvite buildKnown limitation, deferred on purpose
SizeCache.ensurerebuilds the prefix sum from the first dirty index to the end of the list on every commit that measures a row. Measured cost per rebuild: 0.62 ms at 100k rows, 1.95 ms at 100k rows keyed, and 6.2 ms / 20.8 ms at 1 million rows. That is fine at the 100k scale the docs commit to. A Fenwick tree would make it logarithmic and was judged too much to land in the same change as a release; it is a follow-up.Release order
The docs site repo (
react-render-wave-examples) has a matching PR whosepackage.jsonnow requiresreact-render-wave@^3.1.0. Publish this library first, then merge and deploy the site.