react-native-terra-ui 0.7.2 → 0.8.0

package/src/components/screen/ScreenList.tsx

@@ -1,238 +1,260 @@
 import {
   type ComponentPropsWithoutRef,
+  type ComponentPropsWithRef,
   type ComponentType,
   type ElementType,
+  forwardRef,
   type ReactElement,
+  type Ref,
+  type RefAttributes,
   useMemo,
 } from "react";
-import {
-  FlatList,
-  type NativeScrollEvent,
-  type NativeSyntheticEvent,
-  type StyleProp,
-  View,
-  type ViewStyle,
-} from "react-native";
-
-import Animated, {
-  type AnimatedRef,
-  useAnimatedScrollHandler,
-  useComposedEventHandler,
-} from "react-native-reanimated";
+import { FlatList, type FlatListProps, type ListRenderItem, View } from "react-native";
+
+import Animated from "react-native-reanimated";
 import { StyleSheet } from "react-native-unistyles";
 
-import { resolveScreenMargin } from "#theme/screen-margin";
+import { resolveScreenPadding } from "#theme/screen-padding";
 import { PortalHost } from "../portal";
-import { BottomSafeArea } from "./parts/BottomSafeArea";
+import { useScreenRef } from "./hooks/use-screen-ref";
+import { useScreenScrollHandler } from "./hooks/use-screen-scroll-handler";
 import { renderScreenPlaceholder } from "./parts/ScreenPlaceholder";
 import { SCREEN_HEADER_PORTAL_HOST, useScreen } from "./ScreenContext";
-import type { ScreenMargins, ScreenScrollableProps } from "./types";
-import { hasXMargin, hasYMargin, type ListHeaderComponent, renderListHeader } from "./utils";
+import type { ScreenContentPadding, ScreenScrollableProps } from "./types";
+import { hasHorizontalPadding, hasVerticalPadding, renderListComponent } from "./utils";
 
+/** Minimal row information supported by custom list adapters. FlatList also supplies separators. */
 export interface ScreenListRenderItemInfo<T> {
   item: T;
   index: number;
 }
+/** Native viewability token with the item inferred from data. */
+type NativeViewToken = Parameters<
+  NonNullable<FlatListProps<unknown>["onViewableItemsChanged"]>
+>[0]["viewableItems"][number];
+export type ScreenListViewToken<T> = Omit<NativeViewToken, "item"> & { item: T };
+
+type ViewabilityCallback<T> = (info: {
+  viewableItems: ScreenListViewToken<T>[];
+  changed: ScreenListViewToken<T>[];
+}) => void;
+
+type ListLayoutProps = ScreenScrollableProps & {
+  /** @deprecated Use extraBottomPadding. This replaces themed bottom padding; safeArea belongs to Screen. */
+  bottomInset?: number;
+};
 
-export type ScreenListProps<T = unknown, As extends ElementType = typeof FlatList> = ScreenScrollableProps &
+/** Native FlatList props with item inference retained across callbacks and refs. */
+type NativeScreenListProps<T> = ListLayoutProps &
   Omit<
-    ComponentPropsWithoutRef<As>,
+    FlatListProps<T>,
+    | keyof ListLayoutProps
     | "data"
     | "renderItem"
-    | "keyExtractor"
-    | "style"
-    | "contentContainerStyle"
-    | "onScroll"
-    | "ListHeaderComponent"
-    | "ListFooterComponent"
-    | "ListEmptyComponent"
-    | keyof ScreenScrollableProps
+    | "onViewableItemsChanged"
+    | "viewabilityConfigCallbackPairs"
   > & {
-    /**
-     * Which list component to render as. Defaults to React Native's
-     * `FlatList` — pass any list with a FlatList-shaped prop surface
-     * (`data`, `renderItem`, `ListHeaderComponent`, …), e.g. `FlashList`
-     * from `@shopify/flash-list`, or a custom virtualized list.
-     *
-     * Only the default `FlatList` binds the screen's shared imperative
-     * scroll ref — a custom `as` is responsible for its own ref if it needs
-     * one, since not every list exposes a Reanimated-compatible ref (e.g.
-     * `FlashList`'s ref exposes a different, non Reanimated-compatible
-     * imperative API).
-     */
-    as?: As;
+    /** Native FlatList is used by default. */
+    as?: typeof FlatList;
+    /** Null, undefined, and empty data use the empty slot. */
     data?: readonly T[] | null;
-    renderItem?: (info: ScreenListRenderItemInfo<T>) => ReactElement | null;
-    keyExtractor?: (item: T, index: number) => string;
-    ListHeaderComponent?: ListHeaderComponent;
-    ListFooterComponent?: ListHeaderComponent;
-    ListEmptyComponent?: ListHeaderComponent;
-    style?: StyleProp<ViewStyle>;
-    contentContainerStyle?: StyleProp<ViewStyle>;
-    onScroll?: (event: NativeSyntheticEvent<NativeScrollEvent>) => void;
-    /**
-     * Extra bottom padding on the list content — clearance for a tab bar or
-     * home indicator. Defaults to the `layout.screen.margin.y` token when
-     * margins are enabled, otherwise `0`.
-     */
-    bottomInset?: number;
+    /** Render a row, including native separator helpers. */
+    renderItem: ListRenderItem<T>;
+    /** Item-typed native viewability callback. */
+    onViewableItemsChanged?: ViewabilityCallback<T> | null;
+    /** Item-typed native viewability callback/configuration pairs. */
+    viewabilityConfigCallbackPairs?: {
+      viewabilityConfig: NonNullable<FlatListProps<T>["viewabilityConfig"]>;
+      onViewableItemsChanged: ViewabilityCallback<T>;
+    }[];
   };
 
-/**
- * Polymorphic list container — renders whichever list `as` names (defaults
- * to `FlatList`), applying the same margin/header/safe-area/scroll-handler
- * chrome regardless of which one it is. A screen can swap list
- * implementations by changing `as`, without relearning the surrounding API.
- *
- * @example
- * ```tsx
- * <Screen.List data={items} renderItem={({ item }) => <Row item={item} />} />
- * ```
- *
- * @example Any other list component
- * ```tsx
- * import { FlashList } from '@shopify/flash-list';
- *
- * <Screen.List
- *   as={FlashList}
- *   data={items}
- *   renderItem={({ item }) => <Row item={item} />}
- * />
- * ```
- */
-export function ScreenList<T = unknown, As extends ElementType = typeof FlatList>({
-  as,
-  data,
-  renderItem,
-  style,
-  contentContainerStyle,
-  ListHeaderComponent,
-  ListFooterComponent,
-  ListEmptyComponent,
-  horizontal = false,
-  loading = false,
-  LoadingComponent,
-  EmptyComponent,
-  margins,
-  bottomInset,
-  onScroll,
-  ...rest
-}: ScreenListProps<T, As>) {
-  const isDefaultFlatList = as === undefined;
-  const Component = (as ?? FlatList) as ComponentType<Record<string, unknown>>;
+/** Props an adapter must accept and forward to its scrollable list implementation. */
+export type ScreenListAdapterProps<T> = Pick<
+  FlatListProps<T>,
+  | "style"
+  | "contentContainerStyle"
+  | "onScroll"
+  | "ListHeaderComponent"
+  | "ListFooterComponent"
+  | "ListEmptyComponent"
+  | "horizontal"
+  | "scrollEventThrottle"
+  | "contentInsetAdjustmentBehavior"
+  | "automaticallyAdjustContentInsets"
+  | "automaticallyAdjustsScrollIndicatorInsets"
+  | "showsVerticalScrollIndicator"
+  | "snapToOffsets"
+> & {
+  data?: readonly T[] | null;
+  renderItem: (info: ScreenListRenderItemInfo<T>) => ReactElement | null;
+  keyExtractor?: (item: T, index: number) => string;
+};
 
-  // `Animated.createAnimatedComponent` should only run once per component,
-  // not on every render — `as` is arbitrary here (not a fixed module-scope
-  // reference like `Screen.FlatList` uses), so it's memoized on the resolved
-  // component instead of hoisted to module scope.
-  const AnimatedComponent = useMemo(() => Animated.createAnimatedComponent(Component), [Component]);
+type AdapterKeys =
+  | "data"
+  | "renderItem"
+  | "onScroll"
+  | "contentContainerStyle"
+  | "ListHeaderComponent"
+  | "ListFooterComponent"
+  | "ListEmptyComponent";
+
+/** Custom lists must accept the adapter contract and forward a ref for Reanimated. */
+export type ScreenCustomListProps<T, As extends ElementType> = ListLayoutProps &
+  ScreenListAdapterProps<T> &
+  Omit<ComponentPropsWithoutRef<As>, keyof ListLayoutProps | keyof ScreenListAdapterProps<T>> & {
+    as: As &
+      (As extends typeof FlatList
+        ? never
+        : AdapterKeys extends keyof ComponentPropsWithoutRef<As>
+          ? readonly T[] extends NonNullable<ComponentPropsWithoutRef<As>["data"]>
+            ? "ref" extends keyof ComponentPropsWithRef<As>
+              ? unknown
+              : never
+            : never
+          : never);
+    ref?: ComponentPropsWithRef<As>["ref"];
+  };
+
+/** Screen list props, optionally parameterized by a custom adapter component. */
+export type ScreenListProps<
+  T = unknown,
+  As extends ElementType = typeof FlatList,
+> = As extends typeof FlatList ? NativeScreenListProps<T> : ScreenCustomListProps<T, As>;
 
+interface ScreenListComponent {
+  <T>(props: ScreenListProps<T> & RefAttributes<FlatList<T>>): ReactElement | null;
+  <T, As extends ElementType>(props: ScreenCustomListProps<T, As>): ReactElement | null;
+  displayName?: string;
+}
+
+type ImplementationProps = Omit<ScreenListProps<unknown>, "as" | "renderItem"> & {
+  as?: ElementType;
+  renderItem: (info: never) => ReactElement | null;
+};
+
+const ScreenListBase = forwardRef(function ScreenList(
+  {
+    as,
+    data,
+    renderItem,
+    style,
+    contentContainerStyle,
+    ListHeaderComponent,
+    ListFooterComponent,
+    ListEmptyComponent,
+    horizontal = false,
+    isLoading,
+    loading = false,
+    loadingContent,
+    LoadingComponent,
+    emptyContent,
+    EmptyComponent,
+    contentPadding,
+    margins,
+    bottomInset,
+    extraBottomPadding = 0,
+    scrollHandler: externalScrollHandler,
+    onScroll,
+    ...rest
+  }: ImplementationProps,
+  ref: Ref<unknown>
+) {
+  const isDefaultFlatList = as === undefined || as === FlatList;
+  const Component = (as ?? FlatList) as ComponentType<Record<string, unknown>>;
+  // Stable wrappers preserve the native list and its scroll position across renders.
+  const AnimatedComponent = useMemo(() => Animated.createAnimatedComponent(Component), [Component]);
   const {
     background,
     scrollRef,
     scrollHandler,
     headerSnapOffsets,
-    margins: screenMargins,
+    contentPadding: screenPadding,
     hasHeader,
   } = useScreen();
-
-  const resolvedMargins = margins ?? screenMargins;
-  // The placeholder rides in on `ListEmptyComponent` rather than replacing the
-  // list, so the header portal, scroll binding and snap offsets all stay put.
-  // While loading the list is fed an empty `data` so that slot is the one that
-  // renders.
+  const mergedRef = useScreenRef(isDefaultFlatList ? scrollRef : undefined, ref);
+  const resolvedPadding = contentPadding ?? margins ?? screenPadding;
+  const resolvedLoading = isLoading ?? loading;
   const placeholder = renderScreenPlaceholder({
-    loading,
-    LoadingComponent,
-    EmptyComponent,
+    isLoading: resolvedLoading,
+    loadingContent: loadingContent !== undefined ? loadingContent : (LoadingComponent ?? undefined),
+    emptyContent: emptyContent !== undefined ? emptyContent : EmptyComponent,
     isEmpty: !data || data.length === 0,
   });
-
-  const jsScrollHandler = useAnimatedScrollHandler(
-    (event) => {
-      if (onScroll) onScroll(event as unknown as NativeSyntheticEvent<NativeScrollEvent>);
-    },
-    [onScroll]
-  );
-
-  const composedHandler = useComposedEventHandler([scrollHandler, jsScrollHandler]);
-
-  // A caller naming its own `bottomInset` has taken the bottom over entirely,
-  // and a horizontal list has no bottom edge to clear.
-  const needsBottomSafeArea = bottomInset === undefined && !horizontal;
-
-  const footerComponent = (
-    <>
-      {renderListHeader(ListFooterComponent)}
-      {needsBottomSafeArea ? <BottomSafeArea /> : null}
-    </>
-  );
-
-  const headerComponent = (
+  const composedScrollHandler = useScreenScrollHandler(scrollHandler, onScroll, externalScrollHandler);
+  const header = (
     <>
-      {/* `headerWrapper`'s negative margin cancels the list's inherited
-          content padding for the portaled header (`LargeTitlePortalContent`
-          etc. manage their own horizontal padding) — a caller's own
-          `ListHeaderComponent` has no such self-padding, so it stays outside
-          this wrapper and gets the list's normal item padding instead. */}
-      <View style={styles.headerWrapper(resolvedMargins)}>
+      <View style={styles.headerWrapper(resolvedPadding)}>
         <PortalHost name={SCREEN_HEADER_PORTAL_HOST} />
       </View>
-      {renderListHeader(ListHeaderComponent)}
+      {renderListComponent(ListHeaderComponent)}
     </>
   );
 
   return (
     <AnimatedComponent
-      ref={isDefaultFlatList ? (scrollRef as unknown as AnimatedRef<never>) : undefined}
-      data={loading ? [] : data}
+      ref={mergedRef}
+      data={resolvedLoading ? [] : data}
       renderItem={renderItem}
       style={[{ backgroundColor: background }, style]}
       horizontal={horizontal}
-      contentInsetAdjustmentBehavior={hasHeader ? "never" : undefined}
-      contentContainerStyle={[styles.content(resolvedMargins, hasHeader, bottomInset), contentContainerStyle]}
-      ListHeaderComponent={headerComponent}
-      ListFooterComponent={footerComponent}
+      contentInsetAdjustmentBehavior="never"
+      automaticallyAdjustContentInsets={false}
+      automaticallyAdjustsScrollIndicatorInsets={false}
+      contentContainerStyle={[
+        styles.content(resolvedPadding, hasHeader, bottomInset, extraBottomPadding),
+        contentContainerStyle,
+      ]}
+      ListHeaderComponent={header}
+      ListFooterComponent={ListFooterComponent}
       ListEmptyComponent={placeholder ?? ListEmptyComponent}
       showsVerticalScrollIndicator={false}
       scrollEventThrottle={16}
       snapToOffsets={headerSnapOffsets}
       {...rest}
-      onScroll={composedHandler}
+      onScroll={composedScrollHandler}
     />
   );
-}
+});
+
+/**
+ * Virtualized Screen content. FlatList is the default and its native ref and
+ * item callbacks retain their types. Native refreshing keeps rows visible;
+ * isLoading replaces them with loadingContent (a Spinner by default).
+ *
+ * Custom `as` components must implement ScreenListAdapterProps, forward their
+ * ref, and forward the supplied scroll events, styles, and header/footer slots.
+ * Their native ref is forwarded to callers; useScreen().scrollRef is FlatList-only here.
+ * JS onScroll receives nativeEvent data without SyntheticEvent methods.
+ *
+ * @example
+ * ```tsx
+ * <Screen safeArea="auto">
+ *   <Screen.List data={items} renderItem={({ item }) => <Row item={item} />}
+ *     isLoading={isLoading} refreshing={isRefreshing} onRefresh={refresh} />
+ * </Screen>
+ * ```
+ */
+export const ScreenList = ScreenListBase as ScreenListComponent;
 ScreenList.displayName = "Screen.List";
 
-// `resolveScreenMargin` is called *inside* each dynamic function below, not
-// hoisted to the factory's top level — the Babel plugin only attributes a
-// runtime dependency (here, breakpoint) to a style key when the `rt`/
-// `runtime` read it derives from sits inside that key's own value. Hoisting
-// it would silently drop the dependency, so the margin would freeze at
-// whatever breakpoint was active on mount and never update on rotation.
 const styles = StyleSheet.create((theme, runtime) => ({
-  content: (margins: ScreenMargins, hasHeader: boolean, bottomInset: number | undefined) => {
-    const { x: marginX, y: marginY } = resolveScreenMargin(theme, runtime.breakpoint);
+  content: (
+    padding: ScreenContentPadding,
+    hasHeader: boolean,
+    bottomInset: number | undefined,
+    extraBottomPadding: number
+  ) => {
+    const { x, y } = resolveScreenPadding(theme, runtime.breakpoint);
     return {
       flexGrow: 1,
-      // The header is absolutely positioned, so the list reserves its full
-      // height — bar plus top safe area. This assumes the scroll view does not
-      // also get UIKit's automatic inset adjustment: on a native tab screen
-      // that means `disableAutomaticContentInsets` on the tab, or the two
-      // insets are counted twice.
-      paddingTop:
-        (hasHeader ? theme.layout.header.height + runtime.insets.top : 0) +
-        (hasYMargin(margins) ? marginY : 0),
-      paddingHorizontal: hasXMargin(margins) ? marginX : 0,
-      // The safe area is `BottomSafeArea`'s job; counting it here as well
-      // would leave a gap the height of the gesture bar.
-      paddingBottom: bottomInset ?? (hasYMargin(margins) ? marginY : 0),
-    };
-  },
-  headerWrapper: (margins: ScreenMargins) => {
-    const { x: marginX } = resolveScreenMargin(theme, runtime.breakpoint);
-    return {
-      marginHorizontal: hasXMargin(margins) ? -marginX : 0,
+      paddingTop: (hasHeader ? theme.layout.header.height : 0) + (hasVerticalPadding(padding) ? y : 0),
+      paddingHorizontal: hasHorizontalPadding(padding) ? x : 0,
+      paddingBottom: (bottomInset ?? (hasVerticalPadding(padding) ? y : 0)) + extraBottomPadding,
     };
   },
+  headerWrapper: (padding: ScreenContentPadding) => ({
+    marginHorizontal: hasHorizontalPadding(padding) ? -resolveScreenPadding(theme, runtime.breakpoint).x : 0,
+  }),
 }));