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.

Summary by CodeRabbit

Release Notes

• New Features

  • Added deferLaneAssignment option to control lane assignment timing. When enabled, lane assignments are deferred until items are measured for more accurate layout calculations. Defaults to false for backward compatibility.

• Documentation

  • Updated API documentation to clarify lane assignment behavior and document the new configuration option.

[changeset-bot]

🦋 Changeset detected

Latest commit: 8496f50

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]

Pull request overview

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Comments suppressed due to low confidence (1)

packages/virtual-core/src/index.ts:732

• deferLaneAssignment is now part of the memo deps, but toggling it from false → true via setOptions will still keep any existing laneAssignments cached from estimateSize, because getMeasurements prefers cachedLane regardless of deferLaneAssignment. Consider detecting changes to deferLaneAssignment (similar to lanesChangedFlag) and clearing laneAssignments when it changes (at least when switching to true) so the new mode can take effect at runtime.

      this.options.deferLaneAssignment,
    ],
    (count, paddingStart, scrollMargin, getItemKey, enabled, lanes, deferLaneAssignment) => {
      const lanesChanged =
        this.prevLanes !== undefined && this.prevLanes !== lanes

      if (lanesChanged) {
        // Set flag for getMeasurements to handle
        this.lanesChangedFlag = true
      }

      this.prevLanes = lanes
      this.pendingMeasuredCacheIndexes = []

---

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

[coderabbitai]

📝 Walkthrough

Walkthrough

A new deferLaneAssignment option was introduced for the Virtualizer to defer lane caching until items are measured, rather than caching based on estimated sizes. The feature includes implementation changes, comprehensive documentation updates, and test coverage validating the behavior.

Changes

Cohort / File(s)	Summary
Documentation Updates docs/api/virtual-item.md, docs/api/virtualizer.md	Updated lane assignment documentation to explain the new deferLaneAssignment option and clarify that lane assignments are now cached either immediately (based on estimateSize) or deferred until actual measurements, depending on the flag.
Core Implementation packages/virtual-core/src/index.ts	Added deferLaneAssignment?: boolean option to VirtualizerOptions. Modified getMeasurements logic to check if an item has a measured size and conditionally skip caching lane assignments for unmeasured items when deferLaneAssignment is enabled.
Test Coverage packages/virtual-core/tests/index.test.ts	Added two test cases validating lane-caching behavior: one confirming that lane assignments are deferred until measurement when deferLaneAssignment: true, and another confirming immediate caching when the default (false) is used.
Changeset .changeset/loud-insects-itch.md	Added changeset entry documenting the new deferLaneAssignment feature as a patch release for @tanstack/virtual-core.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 A rabbit hops through lanes so fine,
No longer bound by hasty design,
We measured first, then cached with care,
Dynamic layouts bloom everywhere!
Deferred assignments, now set free, 🌱

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title accurately reflects the main feature being introduced: adding a new deferLaneAssignment option to virtual-core.
Description check	✅ Passed	The description follows the template, includes clear explanation of changes, references the resolved issue (#1114), explains the motivation and use case, and confirms testing and changeset generation.
Linked Issues check	✅ Passed	The PR fully addresses issue #1114 by implementing the deferLaneAssignment option that defers lane caching until items are measured, restoring dynamic lane assignment for masonry layouts.
Out of Scope Changes check	✅ Passed	All changes are directly related to implementing the deferLaneAssignment feature: core logic, tests, documentation, and changeset. No unrelated changes are present.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

📝 Coding Plan

• Generate coding plan for human review comments

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

Tip

You can get early access to new features in CodeRabbit.

Enable the early_access setting to enable early access features such as new models, tools, and more.

[coderabbitai]

🧹 Nitpick comments (1)

.changeset/loud-insects-itch.md (1)

1-5: Consider using minor instead of patch for a new feature.

Adding a new option (deferLaneAssignment) is typically a minor version bump according to semver, since it introduces new functionality. While the default behavior is preserved, this may warrant minor rather than patch depending on your project's versioning conventions.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.changeset/loud-insects-itch.md around lines 1 - 5, The changeset currently
marks '@tanstack/virtual-core' as a patch but adds a new feature
(deferLaneAssignment); update the release type from "patch" to "minor" in this
changeset so the version bump follows semver for new functionality—edit the
changeset frontmatter replacing 'patch' with 'minor' for
'@tanstack/virtual-core' (the changeset file is the one that declares the
package and the release type).

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In @.changeset/loud-insects-itch.md:
- Around line 1-5: The changeset currently marks '@tanstack/virtual-core' as a
patch but adds a new feature (deferLaneAssignment); update the release type from
"patch" to "minor" in this changeset so the version bump follows semver for new
functionality—edit the changeset frontmatter replacing 'patch' with 'minor' for
'@tanstack/virtual-core' (the changeset file is the one that declares the
package and the release type).

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: cc9990a2-b929-4bb5-8fee-543be8140f8c

📥 Commits

Reviewing files that changed from the base of the PR and between c939785 and e71a42b.

📒 Files selected for processing (5)

• .changeset/loud-insects-itch.md
• docs/api/virtual-item.md
• docs/api/virtualizer.md
• packages/virtual-core/src/index.ts
• packages/virtual-core/tests/index.test.ts