@legendapp/list 1.0.0-beta.4 → 1.0.0-beta.41

package/README.md

@@ -1,64 +1,120 @@
-# Legend List
+# Legend List 
 
-Legend List aims to be a drop-in replacement for FlatList with much better performance and supporting dynamically sized items.
+**Legend List** is a high-performance list component for **React Native**, written purely in Javascript / Typescript (no native dependencies). It aims to be a drop-in replacement for `FlatList` and/or `FlashList` with better performance, especially when handling dynamically sized items.
 
-## Caution: Experimental
+---
 
-This is an early release to test and gather feedback. It's not used in production yet and needs more work to reach parity with FlatList features.
+## ⚠️ Caution: Experimental ⚠️ 
 
-## Features
+This is an early release to test and gather feedback. It's not used in production yet and needs more work to reach parity with FlatList (and FlashList) features.
 
-In addition to normal FlatList features:
+---
 
--   Dynamic layouts supported. Just use the `estimatedItemSize` prop to give a close estimate so that layouts aren't too far off, and positions will adjust while rendering.
--   `maintainScrollAtEnd`: If true and scroll is within `maintainScrollAtEndThreshold * screen height` then changing items or heights will scroll to the bottom. This can be useful for chat interfaces.
--   `recycleItems` prop enables toggling recycling of list items. If enabled it will reuse item components for improved performance, but it will reuse any local state in items. So if you have local state in items you likely want this disabled.
+## 🤔 Why Legend List?
 
-## Documentation
+*   **Performance:** Designed from the ground up for speed, aiming to outperform `FlatList` in common scenarios.
+*   **Dynamic Item Sizes:** Natively supports items with varying heights without performance hits. Just provide an `estimatedItemSize`.
+*   **Drop-in Potential:** Aims for API compatibility with `FlatList` for easier migration.
+*   **Pure JS/TS:** No native module linking required, ensuring easier integration and compatibility across platforms.
+*   **Lightweight:** Our goal is to keep LegendList as small of a dependency as possible. For more advanced use cases, we plan on supporting optional plugins. This ensures that we keep the package size as small as possible.
 
-See the [documentation site](https://www.legendapp.com/open-source/list) for the full documentation.
+For more information, listen to the podcast we had on [React Native Radio](https://infinite.red/react-native-radio/rnr-325-legend-list-with-jay-meistrich)!
 
-## Usage
+---
+## ✨ Additional Features 
 
-## Install
+Beyond standard `FlatList` capabilities:
 
-`bun add @legendapp/list` or `npm install @legendapp/list` or `yarn add @legendapp/list`
+*   `maintainScrollAtEnd`: (boolean) If `true` and the user is scrolled near the bottom (within `maintainScrollAtEndThreshold * screen height`), the list automatically scrolls to the end when items are added or heights change. Ideal for chat interfaces.
+*   `recycleItems`: (boolean) Toggles item component recycling.
+    *   `true`: Reuses item components for optimal performance. Be cautious if your item components contain local state, as it might be reused unexpectedly.
+    *   `false` (default): Creates new item components every time. Less performant but safer if items have complex internal state.
 
-### Props
+---
 
-We suggest using all of the required props and additionally `keyExtractor` to improve performance when adding/removing items.
+## 📚 Documentation (In Progress)
 
-#### Required
+For comprehensive documentation, guides, and the full API reference, please visit:
 
-```ts
-interface PropsRequired {
-    data: ArrayLike<any> & T[];
-    renderItem: (props: LegendListRenderItemInfo<T>) => ReactNode;
-    estimatedItemSize: number;
-}
-```
+➡️ **[Legend List Documentation Site](https://www.legendapp.com/open-source/list)**
+
+---
+
+## 💻 Usage
 
-#### Optional
+### Installation
 
+```bash
+# Using Bun
+bun add @legendapp/list
+
+# Using npm
+npm install @legendapp/list
+
+# Using Yarn
+yarn add @legendapp/list
+```
+
+### Example
 ```ts
-interface PropsOptional {
-    initialScrollOffset?: number;
-    initialScrollIndex?: number;
-    drawDistance?: number;
-    recycleItems?: boolean;
-    onEndReachedThreshold?: number | null | undefined;
-    maintainScrollAtEnd?: boolean;
-    maintainScrollAtEndThreshold?: number;
-    onEndReached?: ((info: { distanceFromEnd: number }) => void) | null | undefined;
-    keyExtractor?: (item: T, index: number) => string;
+import React, { useRef } from "react"; 
+import { View, Image, Text, StyleSheet } from "react-native";
+import { LegendList, LegendListRef, LegendListRenderItemProps } from "@legendapp/list";
+import { userData } from "../userData"; // Assuming userData is defined elsewhere
+
+// Define the type for your data items
+interface UserData {
+    id: string;
+    name: string;
+    photoUri: string;
 }
+
+const LegendListExample = () => {
+
+    // Optional: Ref for accessing list methods (e.g., scrollTo)
+    const listRef = useRef<LegendListRef | null>(null);
+
+    const renderItem = ({ item }: LegendListRenderItemProps<UserData>) => {
+        return (
+            <View style={styles.itemContainer}>
+                <Image style={styles.profilePic} source={{ uri: item.photoUri }} />
+                <Text style={styles.name}>{item.name}</Text>
+            </View>
+        );
+    };
+
+    return (
+        <LegendList<UserData>
+            // Required Props
+            data={data}
+            renderItem={renderItem} 
+            estimatedItemSize={70} 
+
+            // Strongly Recommended Prop (Improves performance)
+            keyExtractor={(item) => item.id} 
+
+            // Optional Props
+            ref={listRef} 
+            recycleItems={true}   
+            maintainScrollAtEnd={false} 
+            maintainScrollAtEndThreshold={1} 
+
+            // See docs for all available props!
+        />
+    );
+};
+
+export default LegendListExample;
+
 ```
 
-## How to build
+---
+
+## How to Build
 
 `npm run build` will build the package to the `dist` folder.
 
-## How to run example
+## Running the Example
 
 1. `cd example`
 2. `npm i`

package/animated.d.mts

@@ -1,9 +1,58 @@
-import * as react from 'react';
+import * as React$1 from 'react';
 import * as _legendapp_list from '@legendapp/list';
+import * as react_native from 'react-native';
 import { Animated } from 'react-native';
 
-declare const AnimatedLegendList: Animated.AnimatedComponent<(<T>(props: _legendapp_list.LegendListProps<T> & {
-    ref?: react.ForwardedRef<_legendapp_list.LegendListRef>;
-}) => react.ReactElement)>;
+declare const AnimatedLegendList: Animated.AnimatedComponent<(<T>(props: Omit<react_native.ScrollViewProps, "contentOffset" | "contentInset" | "maintainVisibleContentPosition" | "stickyHeaderIndices"> & {
+    alignItemsAtEnd?: boolean;
+    columnWrapperStyle?: _legendapp_list.ColumnWrapperStyle;
+    data: readonly T[];
+    drawDistance?: number;
+    estimatedItemSize?: number;
+    extraData?: any;
+    getEstimatedItemSize?: ((index: number, item: T) => number) | undefined;
+    initialContainerPoolRatio?: number | undefined;
+    initialScrollOffset?: number;
+    initialScrollIndex?: number;
+    ItemSeparatorComponent?: React$1.ComponentType<{
+        leadingItem: T;
+    }> | undefined;
+    keyExtractor?: ((item: T, index: number) => string) | undefined;
+    ListEmptyComponent?: React.ComponentType<any> | React.ReactElement | null | undefined;
+    ListFooterComponent?: React.ComponentType<any> | React.ReactElement | null | undefined;
+    ListFooterComponentStyle?: react_native.StyleProp<react_native.ViewStyle> | undefined;
+    ListHeaderComponent?: React.ComponentType<any> | React.ReactElement | null | undefined;
+    ListHeaderComponentStyle?: react_native.StyleProp<react_native.ViewStyle> | undefined;
+    maintainScrollAtEnd?: boolean;
+    maintainScrollAtEndThreshold?: number;
+    maintainVisibleContentPosition?: boolean;
+    numColumns?: number;
+    onEndReached?: ((info: {
+        distanceFromEnd: number;
+    }) => void) | null | undefined;
+    onEndReachedThreshold?: number | null | undefined;
+    onItemSizeChanged?: ((info: {
+        size: number;
+        previous: number;
+        index: number;
+        itemKey: string;
+        itemData: T;
+    }) => void) | undefined;
+    onRefresh?: () => void;
+    onStartReached?: ((info: {
+        distanceFromStart: number;
+    }) => void) | null | undefined;
+    onStartReachedThreshold?: number | null | undefined;
+    onViewableItemsChanged?: _legendapp_list.OnViewableItemsChanged | undefined;
+    progressViewOffset?: number;
+    recycleItems?: boolean;
+    refScrollView?: React.Ref<react_native.ScrollView>;
+    refreshing?: boolean;
+    renderItem?: ((props: _legendapp_list.LegendListRenderItemProps<T>) => React$1.ReactNode) | undefined;
+    renderScrollComponent?: (props: react_native.ScrollViewProps) => React.ReactElement<react_native.ScrollViewProps>;
+    viewabilityConfig?: _legendapp_list.ViewabilityConfig;
+    viewabilityConfigCallbackPairs?: _legendapp_list.ViewabilityConfigCallbackPairs | undefined;
+    waitForInitialLayout?: boolean;
+} & React$1.RefAttributes<_legendapp_list.LegendListRef>) => React.ReactNode)>;
 
 export { AnimatedLegendList };

package/animated.d.ts

@@ -1,9 +1,58 @@
-import * as react from 'react';
+import * as React$1 from 'react';
 import * as _legendapp_list from '@legendapp/list';
+import * as react_native from 'react-native';
 import { Animated } from 'react-native';
 
-declare const AnimatedLegendList: Animated.AnimatedComponent<(<T>(props: _legendapp_list.LegendListProps<T> & {
-    ref?: react.ForwardedRef<_legendapp_list.LegendListRef>;
-}) => react.ReactElement)>;
+declare const AnimatedLegendList: Animated.AnimatedComponent<(<T>(props: Omit<react_native.ScrollViewProps, "contentOffset" | "contentInset" | "maintainVisibleContentPosition" | "stickyHeaderIndices"> & {
+    alignItemsAtEnd?: boolean;
+    columnWrapperStyle?: _legendapp_list.ColumnWrapperStyle;
+    data: readonly T[];
+    drawDistance?: number;
+    estimatedItemSize?: number;
+    extraData?: any;
+    getEstimatedItemSize?: ((index: number, item: T) => number) | undefined;
+    initialContainerPoolRatio?: number | undefined;
+    initialScrollOffset?: number;
+    initialScrollIndex?: number;
+    ItemSeparatorComponent?: React$1.ComponentType<{
+        leadingItem: T;
+    }> | undefined;
+    keyExtractor?: ((item: T, index: number) => string) | undefined;
+    ListEmptyComponent?: React.ComponentType<any> | React.ReactElement | null | undefined;
+    ListFooterComponent?: React.ComponentType<any> | React.ReactElement | null | undefined;
+    ListFooterComponentStyle?: react_native.StyleProp<react_native.ViewStyle> | undefined;
+    ListHeaderComponent?: React.ComponentType<any> | React.ReactElement | null | undefined;
+    ListHeaderComponentStyle?: react_native.StyleProp<react_native.ViewStyle> | undefined;
+    maintainScrollAtEnd?: boolean;
+    maintainScrollAtEndThreshold?: number;
+    maintainVisibleContentPosition?: boolean;
+    numColumns?: number;
+    onEndReached?: ((info: {
+        distanceFromEnd: number;
+    }) => void) | null | undefined;
+    onEndReachedThreshold?: number | null | undefined;
+    onItemSizeChanged?: ((info: {
+        size: number;
+        previous: number;
+        index: number;
+        itemKey: string;
+        itemData: T;
+    }) => void) | undefined;
+    onRefresh?: () => void;
+    onStartReached?: ((info: {
+        distanceFromStart: number;
+    }) => void) | null | undefined;
+    onStartReachedThreshold?: number | null | undefined;
+    onViewableItemsChanged?: _legendapp_list.OnViewableItemsChanged | undefined;
+    progressViewOffset?: number;
+    recycleItems?: boolean;
+    refScrollView?: React.Ref<react_native.ScrollView>;
+    refreshing?: boolean;
+    renderItem?: ((props: _legendapp_list.LegendListRenderItemProps<T>) => React$1.ReactNode) | undefined;
+    renderScrollComponent?: (props: react_native.ScrollViewProps) => React.ReactElement<react_native.ScrollViewProps>;
+    viewabilityConfig?: _legendapp_list.ViewabilityConfig;
+    viewabilityConfigCallbackPairs?: _legendapp_list.ViewabilityConfigCallbackPairs | undefined;
+    waitForInitialLayout?: boolean;
+} & React$1.RefAttributes<_legendapp_list.LegendListRef>) => React.ReactNode)>;
 
 export { AnimatedLegendList };