Skip to content

Release 3.1.0: headless useVirtualWindow, viewport reveal, scroll control - #1

Merged
sudo-ezekiel merged 4 commits into
mainfrom
release/3.1.0
Sep 10, 2026
Merged

sudo-ezekiel merged 4 commits into
mainfrom
release/3.1.0

Conversation

@sudo-ezekiel

Copy link
Copy Markdown
Owner

Release 3.1.0: headless useVirtualWindow, viewport reveal, scroll control

3.1.0 exposes the windowing engine as a public hook and rebuilds VirtualRenderWave on top of it. Alongside the hook: four new component props, an options object on the handle's scrollTo, 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 of CHANGELOG.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, 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. The first render depends only on the count, the estimate, overscan, scrollMargin, getItemKey and the initial* 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 small batchSize still fills the screen on a long list), initialScrollOffset and initialScrollIndex (read once, applied on the first paint and in server markup), and onRangeChange (fires after commit whenever the rendered or visible range moves).

Handle. scrollTo(index, { align, behavior }). align is "start", "center", "end" or "auto". The old behavior-string form still works.

Fixes. React 18 could not attach a ref to a forwardRef wrapper; types did not resolve under Node16/NodeNext; onEndReached never fired on content shorter than the viewport; programmatic scrolls near the end of a taller-than-estimated list stopped short; initialScrollIndex ignored scrollMargin; align: "auto" oscillated on an item taller than the viewport; NaN scroll targets reset to the top; degenerate itemHeight or overscan mounted every row or none; keyboardNavigation stole keys from focused controls inside rows; the fade-in ignored prefers-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 when getItemKey is set.

CI. .github/workflows/ci.yml runs 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: a WrapperComponent return type that compiles under @types/react 19 fails under 18.

One type change that can break a compile

WrapperProps.ref is now optional and typed RefObject<any> (it was a required RefObject<HTMLElement | null>). Code that reads props.ref.current needs props.ref?.current.

The same change is what lets a custom outerElement or innerElement compile in more than one shape. Before it, only a forwardRef component typed for HTMLElement passed tsc; a forwardRef typed for HTMLDivElement, a plain FC<WrapperProps> attaching the ref itself, an FC reading props.ref?.current, and (under @types/react 19) anything typed FC<WrapperProps> were all rejected. All five shapes compile now, and test/wrapperElements.test.tsx checks them with tsc as 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.

Check Result
vitest, React 19 178 passed, 1 skipped (179 total), 18 files
vitest, React 18 176 passed, 3 skipped
tsc clean on React 18 and React 19
vite build clean
publint no problems
arethetypeswrong green in node10, node16 (CJS), node16 (ESM), bundler
ESM bundle, gzipped 7182 bytes (3.0.0: about 3.7 kB; the growth is the hook)

Known limitation, deferred on purpose

SizeCache.ensure rebuilds 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 whose package.json now requires react-render-wave@^3.1.0. Publish this library first, then merge and deploy the site.

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.
@netlify

netlify Bot commented Sep 10, 2026 •

Copy link
Copy Markdown

❌ Deploy Preview for astonishing-cuchufli-c17417 failed. Why did it fail? →

Name Link
🔨 Latest commit 3760c3f
🔍 Latest deploy log https://app.netlify.com/projects/astonishing-cuchufli-c17417/deploys/6aa25069dd4bbb0008d46bd9

@sudo-ezekiel
sudo-ezekiel merged commit ab3399e into main Sep 10, 2026
3 of 7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant