@legendapp/list 3.4.0 → 3.6.0

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## 3.6.0
+
+- Feat: Add `viewPositionFallback` to align oversized items to the start or end of the viewport during initial or programmatic scrolling, while keeping `viewPosition` alignment for items that fit.
+
+## 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.

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

@@ -225,6 +225,8 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
         index: number;
         viewOffset?: number | undefined;
         viewPosition?: number | undefined;
+        /** Alignment used only when the item exceeds the viewport. Omit to preserve viewPosition. */
+        viewPositionFallback?: "start" | "end";
     };
     /**
      * Initial scroll position in pixels.
@@ -651,6 +653,8 @@ type LegendListRef$1 = {
         index: number;
         viewOffset?: number | undefined;
         viewPosition?: number | undefined;
+        /** Alignment used only when the item exceeds the viewport. Omit to preserve viewPosition. */
+        viewPositionFallback?: "start" | "end";
     }): Promise<void>;
     /**
      * Scrolls to a specific item in the list.
@@ -665,6 +669,8 @@ type LegendListRef$1 = {
         item: any;
         viewOffset?: number | undefined;
         viewPosition?: number | undefined;
+        /** Alignment used only when the item exceeds the viewport. Omit to preserve viewPosition. */
+        viewPositionFallback?: "start" | "end";
     }): Promise<void>;
     /**
      * Scrolls to a specific offset in pixels.

package/keyboard-legacy.d.ts

@@ -190,6 +190,8 @@ type LegendListRef$1 = {
         index: number;
         viewOffset?: number | undefined;
         viewPosition?: number | undefined;
+        /** Alignment used only when the item exceeds the viewport. Omit to preserve viewPosition. */
+        viewPositionFallback?: "start" | "end";
     }): Promise<void>;
     /**
      * Scrolls to a specific item in the list.
@@ -204,6 +206,8 @@ type LegendListRef$1 = {
         item: any;
         viewOffset?: number | undefined;
         viewPosition?: number | undefined;
+        /** Alignment used only when the item exceeds the viewport. Omit to preserve viewPosition. */
+        viewPositionFallback?: "start" | "end";
     }): Promise<void>;
     /**
      * Scrolls to a specific offset in pixels.

package/keyboard.d.ts

@@ -208,6 +208,8 @@ type LegendListRef$1 = {
         index: number;
         viewOffset?: number | undefined;
         viewPosition?: number | undefined;
+        /** Alignment used only when the item exceeds the viewport. Omit to preserve viewPosition. */
+        viewPositionFallback?: "start" | "end";
     }): Promise<void>;
     /**
      * Scrolls to a specific item in the list.
@@ -222,6 +224,8 @@ type LegendListRef$1 = {
         item: any;
         viewOffset?: number | undefined;
         viewPosition?: number | undefined;
+        /** Alignment used only when the item exceeds the viewport. Omit to preserve viewPosition. */
+        viewPositionFallback?: "start" | "end";
     }): Promise<void>;
     /**
      * Scrolls to a specific offset in pixels.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@legendapp/list",
-  "version": "3.4.0",
+  "version": "3.6.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

@@ -225,6 +225,8 @@ interface LegendListSpecificProps<ItemT, TItemType extends string | undefined> {
         index: number;
         viewOffset?: number | undefined;
         viewPosition?: number | undefined;
+        /** Alignment used only when the item exceeds the viewport. Omit to preserve viewPosition. */
+        viewPositionFallback?: "start" | "end";
     };
     /**
      * Initial scroll position in pixels.
@@ -651,6 +653,8 @@ type LegendListRef$1 = {
         index: number;
         viewOffset?: number | undefined;
         viewPosition?: number | undefined;
+        /** Alignment used only when the item exceeds the viewport. Omit to preserve viewPosition. */
+        viewPositionFallback?: "start" | "end";
     }): Promise<void>;
     /**
      * Scrolls to a specific item in the list.
@@ -665,6 +669,8 @@ type LegendListRef$1 = {
         item: any;
         viewOffset?: number | undefined;
         viewPosition?: number | undefined;
+        /** Alignment used only when the item exceeds the viewport. Omit to preserve viewPosition. */
+        viewPositionFallback?: "start" | "end";
     }): Promise<void>;
     /**
      * Scrolls to a specific offset in pixels.
@@ -763,6 +769,8 @@ interface ScrollIndexWithOffset {
     index: number;
     viewOffset?: number;
     viewPosition?: number;
+    /** Alignment used only when the item exceeds the viewport. Omit to preserve viewPosition. */
+    viewPositionFallback?: "start" | "end";
 }
 interface ScrollIndexWithOffsetPosition extends ScrollIndexWithOffset {
     viewPosition?: number;