feat(virtual-core): add deferLaneAssignment option

[2wheeh]

🎯 Changes

resolves #1114

Adds deferLaneAssignment option to defer lane caching until items are measured via measureElement.

#1080 introduced lane assignment caching based on estimateSize for visual stability. However, this broke a core use case for masonry layouts where lane assignments should be based on actual measured sizes, not estimates.

This PR adds a new option deferLaneAssignment (default: false):

• When false (default): Current behavior - lanes cached immediately from estimateSize
• When true: Lanes are calculated but not cached until first measurement, then cached based on actual sizes

✅ Checklist

• I have followed the steps in the Contributing guide.
• I have tested this code locally with pnpm run test:pr.

🚀 Release Impact

• This change affects published code, and I have generated a changeset.

[changeset-bot]

🦋 Changeset detected

Latest commit: 3501a23

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 7 packages

Name	Type
@tanstack/virtual-core	Patch
@tanstack/angular-virtual	Patch
@tanstack/lit-virtual	Patch
@tanstack/react-virtual	Patch
@tanstack/solid-virtual	Patch
@tanstack/svelte-virtual	Patch
@tanstack/vue-virtual	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[Copilot]

Pull request overview

Adds a new deferLaneAssignment option to @tanstack/virtual-core to support masonry-style layouts where lane assignment should be derived from measured sizes (via measureElement/resizeItem) rather than estimateSize, while keeping the existing “stable lanes via caching” behavior as the default.

Changes:

• Introduces deferLaneAssignment?: boolean (default false) and conditionally skips lane caching until an item has been measured.
• Adds tests covering deferred vs immediate lane caching behavior.
• Updates API docs and adds a changeset for release.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/virtual-core/src/index.ts	Adds deferLaneAssignment option + logic to skip caching lanes for unmeasured items
packages/virtual-core/tests/index.test.ts	Adds regression tests for deferred/immediate lane caching
docs/api/virtualizer.md	Documents new option and clarifies lane caching behavior
docs/api/virtual-item.md	Updates lane documentation to mention caching + deferral option
.changeset/loud-insects-itch.md	Publishes the change as a patch release

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

deferLaneAssignment affects how getMeasurements assigns/caches lanes, but getMeasurements is memoized and its deps don’t include this option (via getMeasurementOptions). If setOptions toggles deferLaneAssignment, getMeasurements may return the cached result and/or keep stale laneAssignments, so the new behavior won’t take effect. Include deferLaneAssignment in the memo dependency list (and consider clearing/rebuilding laneAssignments when it changes) so runtime option updates behave correctly.

[Copilot]

The wording “size measured by estimateSize” is inaccurate—estimateSize provides an estimate, not a measurement. Consider rephrasing to “size estimated by estimateSize” to avoid implying it’s based on DOM measurement.

Suggested change

	The lane index of the item. Items are assigned to the shortest lane. Lane assignments are cached immediately based on the size measured by `estimateSize` by default; use `deferLaneAssignment: true` to base assignments on measured sizes instead.
	The lane index of the item. Items are assigned to the shortest lane. Lane assignments are cached immediately based on the size estimated by `estimateSize` by default; use `deferLaneAssignment: true` to base assignments on measured sizes instead.