@legendapp/list 3.7.0

v3.7.0

on Node.js NPM

Fix: List ref methods scrollToIndex, scrollToOffset, scrollToItem, scrollToKey, scrollToEnd, scrollIndexIntoView, and scrollItemIntoView resolve their promises once the scroll lands, or when it is interrupted by user input, canceled or replaced, or cannot reach its target (including removed targets, dataset replacement, and unmounting), instead of resolving early or never.

Suspense/Activity hide counts as unmounting for scroll requests. Requests made through a captured ref while hidden resolve without scrolling and are not replayed on reveal.

scrollToIndex and scrollToOffset clamp out-of-range targets and resolve once landed. Index-based navigation and scrollToEnd on empty data resolve without scrolling, including when a header or footer is present.

Types: new required members on LegendListRef / state since 3.6.0. These stay required, and code that implements or mocks these types must add them:

• LegendListRef (native and web): cancelScroll, scrollToKey, anchorVisibleContent.
• LegendListState: distanceFromEnd, isFollowingEnd. dataKey is added as optional.
• SectionListRef: cancelScroll, scrollToKey, anchorVisibleContent (inherited from LegendListRef). Key-based methods use the flattened keys ${sectionKey}:item:${itemKey}, ${sectionKey}:header, ${sectionKey}:footer, ${sectionKey}:separator:${itemIndex}, and ${sectionKey}:section-separator, where sectionKey is the section's key or section-${sectionIndex}.
• LegendListMetrics, the onMetricsChange payload: unchanged from 3.6.0, still headerSize and footerSize. Scroll position and end-distance fields added during the cycle were removed before release.

getState().listen accepts the new isFollowingEnd key. distanceFromEnd is not a listen key; read getState().distanceFromEnd, which is computed on demand. 3.6.0-shaped listen implementations remain assignable.

Feat: Add ref methods cancelScroll to stop queued and active scrolling, scrollToKey to navigate by stable item key through prepends, and anchorVisibleContent to capture an item's key and viewport offset and hold it through layout changes (the first visible item by default). Pass { key } to choose an item, or use anchorVisibleContent({ hold: false }) for a snapshot without side effects. Returns undefined before initial placement, during dataset replacement, or if no item is found; at the end while following, it returns the anchor without interrupting end following.

Feat: Add viewportMargin: { start, end } to scrollIndexIntoView to keep space clear at the start and end of the viewport along the scroll axis.

Feat: Add itemOffset and itemLength to scrollIndexIntoView and scrollItemIntoView to reveal a region inside an item within viewportMargin on vertical and horizontal lists.

Feat: Expose distanceFromEnd, isFollowingEnd, and dataKey through getState(), and accept isFollowingEnd in getState().listen.

Feat: Add boolean maintainScrollAtEnd.on.dataAppend to follow only additions that preserve existing item keys in order; on.dataChange remains a boolean option for all data changes.

Feat: onUserScroll fires once per accepted real user gesture (native drag with its momentum, web touch/wheel gesture, scroll key press, scrollbar input, or iOS status-bar tap), never for library or list-ref scrolls, and remains @experimental with heuristic wheel grouping and gaps in native pointer/wheel-only and web overlay scrollbar detection.

Fix: With a native screen reader enabled, unowned accessibility scrolling toward the start releases end following and reports onUserScroll once per burst; assistive input during library animations or just after cancelScroll() can be missed, and scrolls bypassing the list (such as native-ref commands or Reanimated scrollTo worklets) cannot be distinguished from accessibility input, so call cancelScroll() on the JS thread before that navigation.

Fix: Leftover trackpad momentum no longer cancels scroll commands; a new wheel gesture can interrupt them, while upward wheel motion releases automatic end following as in 3.6.0 and downward motion never does.

Fix: iOS status-bar taps release end following and settle an interrupted list scroll.

Fix: Native scrolls outside list-owned commands release end following when they move beyond its threshold, and appends while reading earlier rows leave no pending end measurements.

Fix: Pausing maintainScrollAtEnd retains end intent for resuming; isFollowingEnd continues to report that intent while paused.

Fix: Item-layout end following responds to every nonzero size change when its trigger is enabled.

Fix: End thresholds (isAtEnd, onEndReached, and maintainScrollAtEnd) count trailing content and keyboard insets once. With a trailing inset, they now activate closer to the physical end instead of firing early by the inset amount.

Fix: Row measurements and header/footer size changes recheck onStartReached and onEndReached thresholds, so pagination callbacks can fire without a scroll when layout brings an edge within its threshold.

Fix: Animated end following stays aligned through short-list growth, footer and viewport changes, late row measurements, and native drag-to-momentum handoffs. #563 #568

Fix: Automatic native end following waits for a drag and its momentum to settle, then catches up near the end using the configured threshold.

Fix: Keyed scroll targets survive prepends and same-key item updates, cached dataset switches restart initial placement, and fixed-size updates and cache clearing preserve the reader's anchor.

Fix: scrollToOffset can reach contentContainerStyle minimum sizes, horizontal RTL web lists use the scroll owner's direction for offsets, and horizontal RTL scroll-offset conversion keeps numeric minWidth in the physical content extent.

Fix: When getFixedItemSize is set, changing extraData invalidates all fixed sizes and repositions the data.

Fix: Inline onMetricsChange callbacks no longer cause repeated metrics emissions.

Fix: End following rearms when a scroll or gesture settles within maintainScrollAtEndThreshold, so new content resumes following after scrollToIndex/scrollToOffset or a small nudge that stays near the end.

Fix: When getFixedItemSize starts returning sizes for rows that were already measured, their stale measurements are dropped and the fixed sizes are applied, including rows reordered in the same render.

Fix: Web lists follow the end in one painted frame when every row grows after a mount or dataKey switch, instead of clamping against the stale content extent and catching up a frame late.

Fix: On Fabric, the native content extent commits in the same render pass as row positions, so shrinking content cannot briefly leave rows mispositioned.

Fix: scrollMessageToEnd({ closeKeyboard: true }) starts scrolling right away and eases to the closed end in one motion while the keyboard closes, dismissing it once, including back-to-back and mixed animated and non-animated sends.

Fix: AnimatedLegendList itemLayoutAnimation no longer animates rows while scrolling, during list scroll commands, or after layout adjustments, and skips the transition when a container switches items even without recycleItems.

Fix: Keyboard occlusion is excluded from viewability calculations, horizontal viewability uses the correct start padding including RTL, native content insets are counted only where applied, and KeyboardAwareLegendList keeps the static contentInset prop out of Android keyboard inset reports so it is not counted twice.

Fix: scrollMessageToEnd({ closeKeyboard: true }) freezes keyboard tracking before the keyboard starts closing, so the list scrolls to the end in one motion instead of first moving back with the closing keyboard. A rejected scroll or a keyboard close that never settles no longer leaves freeze set. #557

Fix: Animated scrolls that start past the end of the content ease back into range instead of snapping.

Perf: With recycleItems enabled, reuse warm offscreen rows before empty containers, and skip key extraction for unchanged append prefixes.