Skip to content

Commit 0c68e81

Browse files
fix: harden scroll-target and initial-index handling (#1444)
* fix: clamp initial top-most item index to the available range getInitialTopMostItemIndexNumber returned the raw index without bounds checking, so an out-of-range initialTopMostItemIndex (e.g. after the data set shrinks) could start the list at a blank or mid-list position. Clamp the resolved index to [0, lastIndex], mirroring the scroll-target clamp in originalIndexFromLocation. * test: cover getInitialTopMostItemIndexNumber clamping * chore: add changeset for initial top-most index clamp * fix: avoid mutating the location passed to scrollToIndex normalizeIndexLocation applied its align/behavior/offset defaults directly onto the caller's location object. Apply them to a shallow copy instead so a shared or memoized location is left untouched. * test: cover normalizeIndexLocation immutability and defaults * fix: treat initialTopMostItemIndex { index: 0 } the same as 0 The didMount filters compared the raw initialTopMostItemIndex against the number 0, so { index: 0 } was treated as a non-default location, triggering a redundant initial scroll and delaying followOutput. Add initialTopMostItemIndexIsZero so both forms are handled the same. * test: cover initialTopMostItemIndexIsZero for numeric and object forms * chore: describe the scroll-target and initial-index fixes in a single changeset * fix: preserve initial index zero positioning options * chore: format initial index changeset --------- Co-authored-by: Petyo Ivanov <[email protected]>
1 parent b019057 commit 0c68e81

7 files changed

Lines changed: 150 additions & 4 deletions
Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
---
2+
'react-virtuoso': patch
3+
---
4+
5+
Harden scroll-target and initial-index handling:
6+
7+
- Clamp the initial top-most item index to the available range, so an out-of-range `initialTopMostItemIndex` (for example after the data set shrinks) no longer starts the list at a blank or mid-list position.
8+
- Stop mutating the location object passed to `scrollToIndex`; `normalizeIndexLocation` now applies its defaults to a shallow copy.
9+
- Treat a default-positioned `initialTopMostItemIndex` of `{ index: 0 }` the same as `0`, avoiding a redundant initial scroll and a delayed `followOutput`.

‎packages/react-virtuoso/src/initialTopMostItemIndexSystem.ts‎

Lines changed: 15 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,19 @@ import type { FlatIndexLocationWithAlign } from './interfaces'
1111
export function getInitialTopMostItemIndexNumber(location: FlatIndexLocationWithAlign | number, totalCount: number): number {
1212
const lastIndex = totalCount - 1
1313
const index = typeof location === 'number' ? location : location.index === 'LAST' ? lastIndex : location.index
14-
return index
14+
return Math.max(0, Math.min(index, lastIndex))
15+
}
16+
17+
export function initialTopMostItemIndexIsZero(location: FlatIndexLocationWithAlign | number): boolean {
18+
if (typeof location === 'number') {
19+
return location === 0
20+
}
21+
22+
return (
23+
location.index === 0 &&
24+
(location.align === undefined || location.align === 'start') &&
25+
(location.offset === undefined || location.offset === 0)
26+
)
1527
}
1628

1729
export const initialTopMostItemIndexSystem = u.system(
@@ -24,7 +36,7 @@ export const initialTopMostItemIndexSystem = u.system(
2436
u.pipe(
2537
didMount,
2638
u.withLatestFrom(initialTopMostItemIndex),
27-
u.filter(([_, location]) => location !== 0),
39+
u.filter(([_, location]) => !initialTopMostItemIndexIsZero(location)),
2840
u.mapTo(false)
2941
),
3042
scrolledToInitialItem
@@ -33,7 +45,7 @@ export const initialTopMostItemIndexSystem = u.system(
3345
u.pipe(
3446
didMount,
3547
u.withLatestFrom(initialTopMostItemIndex),
36-
u.filter(([_, location]) => location !== 0),
48+
u.filter(([_, location]) => !initialTopMostItemIndexIsZero(location)),
3749
u.mapTo(false)
3850
),
3951
initialItemFinalLocationReached

‎packages/react-virtuoso/src/scrollToIndexSystem.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ export type IndexLocation = IndexLocationWithAlign | number
1111
const SUPPORTS_SCROLL_TO_OPTIONS = typeof document !== 'undefined' && 'scrollBehavior' in document.documentElement.style
1212

1313
export function normalizeIndexLocation(location: IndexLocation) {
14-
const result: IndexLocationWithAlign = typeof location === 'number' ? { index: location } : location
14+
const result: IndexLocationWithAlign = typeof location === 'number' ? { index: location } : { ...location }
1515

1616
if (!result.align) {
1717
result.align = 'start'
Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
import { describe, expect, it } from 'vitest'
2+
3+
import { initialTopMostItemIndexIsZero } from '../src/initialTopMostItemIndexSystem'
4+
5+
describe('initialTopMostItemIndexIsZero', () => {
6+
it('treats the numeric 0 as zero', () => {
7+
expect(initialTopMostItemIndexIsZero(0)).toBe(true)
8+
})
9+
10+
it('treats { index: 0 } the same as the numeric 0', () => {
11+
expect(initialTopMostItemIndexIsZero({ index: 0 })).toBe(true)
12+
expect(initialTopMostItemIndexIsZero({ align: 'start', index: 0 })).toBe(true)
13+
expect(initialTopMostItemIndexIsZero({ behavior: 'smooth', index: 0 })).toBe(true)
14+
})
15+
16+
it('does not treat zero index locations with explicit positioning as zero', () => {
17+
expect(initialTopMostItemIndexIsZero({ align: 'center', index: 0 })).toBe(false)
18+
expect(initialTopMostItemIndexIsZero({ align: 'end', index: 0 })).toBe(false)
19+
expect(initialTopMostItemIndexIsZero({ index: 0, offset: 40 })).toBe(false)
20+
})
21+
22+
it('reports a non-zero numeric index', () => {
23+
expect(initialTopMostItemIndexIsZero(5)).toBe(false)
24+
})
25+
26+
it('reports a non-zero location index', () => {
27+
expect(initialTopMostItemIndexIsZero({ index: 5 })).toBe(false)
28+
})
29+
30+
it("does not treat 'LAST' as zero", () => {
31+
expect(initialTopMostItemIndexIsZero({ index: 'LAST' })).toBe(false)
32+
})
33+
})
Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
import { describe, expect, it } from 'vitest'
2+
3+
import { getInitialTopMostItemIndexNumber } from '../src/initialTopMostItemIndexSystem'
4+
5+
describe('getInitialTopMostItemIndexNumber', () => {
6+
const totalCount = 50
7+
const lastIndex = totalCount - 1
8+
9+
it('clamps an out-of-range numeric index down to the last index', () => {
10+
expect(getInitialTopMostItemIndexNumber(200, totalCount)).toBe(lastIndex)
11+
})
12+
13+
it('clamps an out-of-range location index down to the last index', () => {
14+
expect(getInitialTopMostItemIndexNumber({ index: 200 }, totalCount)).toBe(lastIndex)
15+
})
16+
17+
it('clamps a negative index up to zero', () => {
18+
expect(getInitialTopMostItemIndexNumber(-5, totalCount)).toBe(0)
19+
expect(getInitialTopMostItemIndexNumber({ index: -5 }, totalCount)).toBe(0)
20+
})
21+
22+
it('returns an in-range index unchanged', () => {
23+
expect(getInitialTopMostItemIndexNumber(20, totalCount)).toBe(20)
24+
expect(getInitialTopMostItemIndexNumber({ index: 20 }, totalCount)).toBe(20)
25+
})
26+
27+
it("resolves 'LAST' to the last index", () => {
28+
expect(getInitialTopMostItemIndexNumber({ index: 'LAST' }, totalCount)).toBe(lastIndex)
29+
})
30+
31+
it('clamps to zero for an empty list', () => {
32+
expect(getInitialTopMostItemIndexNumber({ index: 5 }, 0)).toBe(0)
33+
})
34+
})

‎packages/react-virtuoso/test/listSystem.test.ts‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,6 +160,37 @@ describe('list engine', () => {
160160
}, 100)
161161
})
162162
})
163+
164+
it('applies initial location options when the initial index is zero', () => {
165+
const SIZE = 30
166+
const OFFSET = 40
167+
const { fixedItemHeight, initialTopMostItemIndex, listState, propsReady, scrollTo, scrollTop, totalCount, viewportHeight } =
168+
init(listSystem)
169+
170+
publish(initialTopMostItemIndex, { index: 0, offset: OFFSET })
171+
publish(scrollTop, 0)
172+
publish(viewportHeight, 200)
173+
publish(totalCount, 1000)
174+
publish(propsReady, true)
175+
publish(fixedItemHeight, SIZE)
176+
expect(getValue(listState)).toMatchObject({
177+
items: [],
178+
})
179+
180+
const sub = vi.fn()
181+
subscribe(scrollTo, sub)
182+
183+
return new Promise((resolve) => {
184+
setTimeout(() => {
185+
expect(sub).toHaveBeenCalledWith({
186+
behavior: 'auto',
187+
top: OFFSET,
188+
})
189+
190+
resolve(true)
191+
}, 100)
192+
})
193+
})
163194
})
164195

165196
describe('scroll to index', () => {
Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
import { describe, expect, it } from 'vitest'
2+
3+
import { normalizeIndexLocation } from '../src/scrollToIndexSystem'
4+
5+
describe('normalizeIndexLocation', () => {
6+
it('does not mutate the passed location object', () => {
7+
const location = { index: 5 }
8+
normalizeIndexLocation(location)
9+
expect(location).toEqual({ index: 5 })
10+
})
11+
12+
it('returns a new object with the defaults applied', () => {
13+
const location = { index: 5 }
14+
const result = normalizeIndexLocation(location)
15+
expect(result).not.toBe(location)
16+
expect(result).toEqual({ align: 'start', behavior: 'auto', index: 5, offset: 0 })
17+
})
18+
19+
it('preserves explicitly provided fields', () => {
20+
const result = normalizeIndexLocation({ align: 'center', index: 2, offset: 10 })
21+
expect(result).toMatchObject({ align: 'center', index: 2, offset: 10 })
22+
})
23+
24+
it('wraps a numeric location into an object with defaults', () => {
25+
expect(normalizeIndexLocation(7)).toEqual({ align: 'start', behavior: 'auto', index: 7, offset: 0 })
26+
})
27+
})

0 commit comments

Comments
 (0)