@shopify/flash-list 2.0.0 → 2.0.2-rc.1

package/src/FlashListProps.ts

@@ -6,7 +6,8 @@ import {
   ViewStyle,
 } from "react-native";
 
-import ViewToken from "./recyclerview/viewability/ViewToken";
+import { BlankAreaEventHandler } from "./native/auto-layout/AutoLayoutView";
+import ViewToken from "./viewability/ViewToken";
 
 export interface ListRenderItemInfo<TItem> {
   item: TItem;
@@ -39,6 +40,18 @@ export type ListRenderItem<TItem> = (
   info: ListRenderItemInfo<TItem>
 ) => React.ReactElement | null;
 
+export type ContentStyle = Pick<
+  ViewStyle,
+  | "backgroundColor"
+  | "paddingTop"
+  | "paddingLeft"
+  | "paddingRight"
+  | "paddingBottom"
+  | "padding"
+  | "paddingVertical"
+  | "paddingHorizontal"
+>;
+
 export interface ViewabilityConfigCallbackPair<TItem> {
   viewabilityConfig: ViewabilityConfig;
   onViewableItemsChanged:
@@ -76,6 +89,14 @@ export interface FlashListProps<TItem>
    */
   data: ReadonlyArray<TItem> | null | undefined;
 
+  /**
+   * Average or median size for elements in the list. Doesn't have to be very accurate but a good estimate can improve performance.
+   * A quick look at `Element Inspector` can help you determine this. If you're confused between two values, the smaller value is a better choice.
+   * For vertical lists provide average height and for horizontal average width.
+   * Read more about it here: https://shopify.github.io/flash-list/docs/estimated-item-size
+   */
+  estimatedItemSize?: number;
+
   /**
    * Each cell is rendered using this element.
    * Can be a React Component Class, or a render function.
@@ -144,11 +165,30 @@ export interface FlashListProps<TItem>
     | React.ComponentType<ScrollViewProps>
     | React.FC<ScrollViewProps>;
 
+  /**
+   * You can use `contentContainerStyle` to apply padding that will be applied to the whole content itself.
+   * For example, you can apply this padding, so that all of your items have leading and trailing space.
+   */
+  contentContainerStyle?: ContentStyle;
+
   /**
    * Draw distance for advanced rendering (in dp/px)
    */
   drawDistance?: number;
 
+  /**
+   * Specifies how far the first item is drawn from start of the list window or, offset of the first item of the list (not the header).
+   * Needed if you're using initialScrollIndex prop. Before the initial draw the list cannot figure out the size of header or, any special margin/padding that might have been applied
+   * using header styles etc.
+   * If this isn't provided initialScrollIndex might not scroll to the provided index.
+   */
+  estimatedFirstItemOffset?: number;
+
+  /**
+   * Visible height and width of the list. This is not the scroll content size.
+   */
+  estimatedListSize?: { height: number; width: number };
+
   /**
    * A marker property for telling the list to re-render (since it implements PureComponent).
    * If any of your `renderItem`, Header, Footer, etc. functions depend on anything outside of the `data` prop,
@@ -166,6 +206,11 @@ export interface FlashListProps<TItem>
    */
   initialScrollIndex?: number | null | undefined;
 
+  /**
+   * Reverses the direction of scroll. Uses scale transforms of -1.
+   */
+  inverted?: boolean | null | undefined;
+
   /**
    * Used to extract a unique key for a given item at the specified index.
    * Key is used for optimizing performance. Defining `keyExtractor` is also necessary
@@ -180,6 +225,18 @@ export interface FlashListProps<TItem>
    */
   numColumns?: number | undefined;
 
+  /**
+   * Computes blank space that is visible to the user during scroll or list load. If list doesn't have enough items to fill the screen even then this will be raised.
+   * Values reported: {
+   *    offsetStart -> visible blank space on top of the screen (while going up). If value is greater than 0 then it's visible to user.
+   *    offsetEnd -> visible blank space at the end of the screen (while going down). If value is greater than 0 then it's visible to user.
+   *    blankArea -> max(offsetStart, offsetEnd) use this directly and look for values > 0
+   * }
+   * Please note that this event isn't synced with onScroll event but works with native onDraw/layoutSubviews. Events with values > 0 are blanks.
+   * This event is raised even when there is no visible blank with negative values for extensibility however, for most use cases check blankArea > 0 and use the value.
+   */
+  onBlankArea?: BlankAreaEventHandler;
+
   /**
    * Called once when the scroll position gets within onEndReachedThreshold of the rendered content.
    */
@@ -235,7 +292,11 @@ export interface FlashListProps<TItem>
   ) => string | number | undefined;
 
   /**
-   * This method can be used to change column span of an item.
+   * This method can be used to provide explicit size estimates or change column span of an item.
+   *
+   * Providing specific estimates is a good idea when you can calculate sizes reliably. FlashList will prefer this value over `estimatedItemSize` for that specific item.
+   * Precise estimates will also improve precision of `scrollToIndex` method and `initialScrollIndex` prop. If you have a `separator` below your items you can include its size in the estimate.
+   *
    * Changing item span is useful when you have grid layouts (numColumns > 1) and you want few items to be bigger than the rest.
    *
    * Modify the given layout. Do not return. FlashList will fallback to default values if this is ignored.
@@ -243,7 +304,7 @@ export interface FlashListProps<TItem>
    * Performance: This method is called very frequently. Keep it fast.
    */
   overrideItemLayout?: (
-    layout: { span?: number },
+    layout: { span?: number; size?: number },
     item: TItem,
     index: number,
     maxColumns: number,
@@ -281,6 +342,21 @@ export interface FlashListProps<TItem>
     | ViewabilityConfigCallbackPairs<TItem>
     | undefined;
 
+  /**
+   * FlashList attempts to measure size of horizontal lists by drawing an extra list item in advance. This can sometimes cause issues when used with `initialScrollIndex` in lists
+   * with very little content. You might see some amount of over scroll. When set to true the list's rendered size needs to be deterministic (i.e., height and width greater than 0)
+   * as FlashList will skip rendering the extra item for measurement. Default value is `false`.
+   */
+  disableHorizontalListHeightMeasurement?: boolean;
+
+  /**
+   * FlashList applies some fixes to layouts of its children which can conflict with custom `CellRendererComponent`
+   * implementations. You can disable this behavior by setting this to `true`.
+   * Recommendation: Set this to `true` while you apply special behavior to the `CellRendererComponent`. Once done set this to
+   * `false` again.
+   */
+  disableAutoLayout?: boolean;
+
   /**
    * New arch only
    * Maximum number of items in the recycle pool. These are the items that are cached in the recycle pool when they are scrolled off the screen.

package/src/GridLayoutProviderWithProps.ts

@@ -0,0 +1,180 @@
+import {
+  Dimension,
+  GridLayoutProvider,
+  Layout,
+  LayoutManager,
+} from "recyclerlistview";
+
+import { FlashListProps } from "./FlashListProps";
+import { AverageWindow } from "./utils/AverageWindow";
+import { applyContentContainerInsetForLayoutManager } from "./utils/ContentContainerUtils";
+
+export default class GridLayoutProviderWithProps<T> extends GridLayoutProvider {
+  private props: FlashListProps<T>;
+  private layoutObject = { span: undefined, size: undefined };
+  private averageWindow: AverageWindow;
+  private renderWindowInsets: Dimension = { width: 0, height: 0 };
+  private _hasExpired = false;
+  public defaultEstimatedItemSize = 100;
+
+  constructor(
+    maxSpan: number,
+    getLayoutType: (
+      index: number,
+      props: FlashListProps<T>,
+      mutableLayout: { span?: number; size?: number }
+    ) => string | number,
+    getSpan: (
+      index: number,
+      props: FlashListProps<T>,
+      mutableLayout: { span?: number; size?: number }
+    ) => number,
+    getHeightOrWidth: (
+      index: number,
+      props: FlashListProps<T>,
+      mutableLayout: { span?: number; size?: number }
+    ) => number | undefined,
+    props: FlashListProps<T>,
+    acceptableRelayoutDelta?: number
+  ) {
+    super(
+      maxSpan,
+      (i) => {
+        return getLayoutType(i, this.props, this.getCleanLayoutObj());
+      },
+      (i) => {
+        return getSpan(i, this.props, this.getCleanLayoutObj());
+      },
+      (i) => {
+        return (
+          // Using average item size if no override has been provided by the developer
+          getHeightOrWidth(i, this.props, this.getCleanLayoutObj()) ??
+          this.averageItemSize
+        );
+      },
+      acceptableRelayoutDelta
+    );
+    this.props = props;
+    this.averageWindow = new AverageWindow(
+      1,
+      props.estimatedItemSize ?? this.defaultEstimatedItemSize
+    );
+    this.renderWindowInsets = this.getAdjustedRenderWindowSize(
+      this.renderWindowInsets
+    );
+  }
+
+  public updateProps(props: FlashListProps<T>): GridLayoutProviderWithProps<T> {
+    const newInsetValues = applyContentContainerInsetForLayoutManager(
+      {
+        height: 0,
+        width: 0,
+      },
+      props.contentContainerStyle,
+      Boolean(props.horizontal)
+    );
+    this._hasExpired =
+      this._hasExpired ||
+      this.props.numColumns !== props.numColumns ||
+      newInsetValues.height !== this.renderWindowInsets.height ||
+      newInsetValues.width !== this.renderWindowInsets.width;
+    this.renderWindowInsets = newInsetValues;
+    this.props = props;
+    return this;
+  }
+
+  /**
+   * This methods returns true if the layout provider has expired and needs to be recreated.
+   * This can happen if the number of columns has changed or the render window size has changed in a way that cannot be handled by the layout provider internally.
+   */
+  public get hasExpired() {
+    return this._hasExpired;
+  }
+
+  /**
+   * Calling this method will mark the layout provider as expired. As a result, a new one will be created by FlashList and old cached layouts will be discarded.
+   */
+  public markExpired() {
+    this._hasExpired = true;
+  }
+
+  /**
+   * Calling this method will help the layout provider track average item sizes on its own
+   * Overriding layout manager can help achieve the same thing without relying on this method being called however, it will make implementation very complex for a simple use case
+   * @param index Index of the item being reported
+   */
+  public reportItemLayout(index: number) {
+    const layout = this.getLayoutManager()?.getLayouts()[index];
+    if (layout) {
+      // For the same index we can now return different estimates because average is updated in realtime
+      // Marking the layout as overridden will help layout manager avoid using the average after initial measurement
+      layout.isOverridden = true;
+      this.averageWindow.addValue(
+        this.props.horizontal ? layout.width : layout.height
+      );
+    }
+  }
+
+  public get averageItemSize() {
+    return this.averageWindow.currentValue;
+  }
+
+  public newLayoutManager(
+    renderWindowSize: Dimension,
+    isHorizontal?: boolean,
+    cachedLayouts?: Layout[]
+  ): LayoutManager {
+    // Average window is updated whenever a new layout manager is created. This is because old values are not relevant anymore.
+    const estimatedItemCount = Math.max(
+      3,
+      Math.round(
+        (this.props.horizontal
+          ? renderWindowSize.width
+          : renderWindowSize.height) /
+          (this.props.estimatedItemSize ?? this.defaultEstimatedItemSize)
+      )
+    );
+    this.averageWindow = new AverageWindow(
+      2 * (this.props.numColumns || 1) * estimatedItemCount,
+      this.averageWindow.currentValue
+    );
+    const newLayoutManager = super.newLayoutManager(
+      this.getAdjustedRenderWindowSize(renderWindowSize),
+      isHorizontal,
+      cachedLayouts
+    );
+    if (cachedLayouts) {
+      this.updateCachedDimensions(cachedLayouts, newLayoutManager);
+    }
+    return newLayoutManager;
+  }
+
+  private updateCachedDimensions(
+    cachedLayouts: Layout[],
+    layoutManager: LayoutManager
+  ) {
+    const layoutCount = cachedLayouts.length;
+    for (let i = 0; i < layoutCount; i++) {
+      cachedLayouts[i] = {
+        ...cachedLayouts[i],
+        // helps in updating the fixed dimension of layouts e.g, width in case of horizontal list
+        // updating them in advance will make sure layout manager won't try to fit more items in the same row or column
+        ...layoutManager.getStyleOverridesForIndex(i),
+      };
+    }
+  }
+
+  private getCleanLayoutObj() {
+    this.layoutObject.size = undefined;
+    this.layoutObject.span = undefined;
+    return this.layoutObject;
+  }
+
+  private getAdjustedRenderWindowSize(renderWindowSize: Dimension) {
+    return applyContentContainerInsetForLayoutManager(
+      { ...renderWindowSize },
+      this.props.contentContainerStyle,
+      Boolean(this.props.horizontal)
+    );
+  }
+}