@legendapp/list 3.3.11 → 3.5.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## 3.5.0
+
+- Feat: Add `scrollElement` so web lists can share an ancestor element's scrollbar
+- Fix: Stopping scrolling keeps rows prepared in the last scroll direction instead of shifting the render buffer backward.
+- Perf: Single-column lists do less layout work during initial rendering and scrolling when item sizes and data are unchanged.
+
+## 3.4.0
+
+- Feat: Add `onReady`, called after each initial placement and scroll cycle completes, including cycles restarted by a `dataKey` change.
+- Fix: End-following and animated programmatic scrolling now stay aligned through footer, viewport, and native layout changes, while user dragging cancels queued follow requests.
+- Fix: `onStartReached` and `onEndReached` callbacks now fire reliably after layout and dataset resets, including short lists and gestures that cross a threshold over multiple events.
+- Fix: Numeric `initialScrollIndex` values that target the last row now include the footer when opening at the end.
+- Perf: Fast scrolling now prepares rows in the direction you are moving, including upward and end-aligned scrolling, so the next content is ready sooner.
+
 ## 3.3.11
 
 - Fix: `scrollToEnd` and `maintainScrollAtEnd` keep reaching the end as content changes, while scrolling away or requesting another position cancels automatic following.

package/README.md

@@ -112,6 +112,39 @@ export default LegendListExample
 
 ---
 
+### Sharing a scrollbar on the web
+
+React DOM lists can use an ancestor element's scrollbar with `scrollElement`:
+
+```tsx
+import { LegendList } from "@legendapp/list/react";
+import { useState } from "react";
+
+function History({ swaps, renderSwap }) {
+    const [scrollElement, setScrollElement] = useState<HTMLDivElement | null>(null);
+
+    return (
+        <div ref={setScrollElement} style={{ height: 600, overflow: "auto" }}>
+            <ProfileHeader />
+            <LegendList
+                data={swaps}
+                renderItem={renderSwap}
+                keyExtractor={(swap) => swap.id}
+                scrollElement={scrollElement}
+            />
+        </div>
+    );
+}
+```
+
+Use a state-backed callback ref so the list receives the element after mounting and whenever it changes. `null` waits for an external element; `undefined` keeps the default list-owned scrollbar. The element must be an ancestor of the list. Keep the list's own height unconstrained so its content contributes to the parent's scroll range.
+
+Multiple lists can share the same element, including lists in separate columns. Each uses the owner's viewport on the scroll axis and its own width/height on the cross axis. Content above the list is accounted for automatically, including preceding content that resizes. `scrollToIndex`, `scrollToOffset`, and `scrollToEnd` remain list-relative and move the shared owner.
+
+`maintainVisibleContentPosition` anchors changes to the list's own rows; it does not freeze the layout of surrounding content. An offscreen list does not pull the owner back into view to apply a measurement correction.
+
+`useWindowScroll` continues to use the browser window. Both modes share the same web implementation; `scrollElement` takes precedence when provided. As with window scrolling, external mode does not configure the owner's scrollbar styling or CSS snapping. It is not supported with `renderScrollComponent`.
+
 ## How to Build
 
 1. `bun i`

package/animated.d.ts

@@ -333,6 +333,12 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
     onLoad?: (info: {
         elapsedTimeInMs: number;
     }) => void;
+    /**
+     * Called after layout and initial scrolling complete, including after a
+     * dataKey reset. Unlike onLoad, this runs for each initial placement cycle.
+     * Ordinary data updates do not trigger it unless they restart initial placement.
+     */
+    onReady?: () => void;
     /**
      * Called when list layout metrics change.
      */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@legendapp/list",
-  "version": "3.3.11",
+  "version": "3.5.0",
   "description": "Legend List is a drop-in replacement for FlatList with much better performance and supporting dynamically sized items.",
   "sideEffects": false,
   "private": false,

package/react-native.d.ts

@@ -333,6 +333,12 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
     onLoad?: (info: {
         elapsedTimeInMs: number;
     }) => void;
+    /**
+     * Called after layout and initial scrolling complete, including after a
+     * dataKey reset. Unlike onLoad, this runs for each initial placement cycle.
+     * Ordinary data updates do not trigger it unless they restart initial placement.
+     */
+    onReady?: () => void;
     /**
      * Called when list layout metrics change.
      */