react-native-terra-ui 0.7.2 → 0.8.0

package/src/components/screen/ScreenContext.tsx

@@ -9,70 +9,78 @@ import Animated, {
   useSharedValue,
 } from "react-native-reanimated";
 
-import type { ScreenMargins } from "./types";
+import type { ScreenContentPadding, ScreenSafeArea } from "./types";
 
+/** Internal animated ref shared by the screen's primary scroll container. */
 export type ScreenScrollRef = AnimatedRef<Animated.ScrollView>;
 
-/** `PortalHost` name shared by `Screen.ScrollView` / `Screen.FlatList` and header variants that portal content into them. */
+/** Local portal target for scrollable header content. */
 export const SCREEN_HEADER_PORTAL_HOST = "screen-header";
 
+/** Shared configuration and UI-thread scroll values returned by `useScreen`. */
 export interface ScreenContextValue {
   /**
-   * Which axes scroll containers pad with `layout.screen.margin`.
-   * Overridable per `Screen.ScrollView` / `Screen.FlatList` / `Screen.List`
-   * via their own `margins` prop.
+   * Which axes scroll containers pad with `layout.screen.padding`.
+   * Each scroll container can override this with its own `contentPadding` prop.
    */
-  margins: ScreenMargins;
+  contentPadding: ScreenContentPadding;
+  /** Safe-area policy applied by the root; descendants must not reapply it. */
+  safeArea: ScreenSafeArea;
+  /** @deprecated Use contentPadding. */
+  margins: ScreenContentPadding;
   /** Whether a `Screen.Header` is present. Used by scroll containers to add top inset. */
   hasHeader: boolean;
-  /**
-   * Live vertical scroll offset of the screen's scroll container, driven by
-   * `Screen.ScrollView` / `Screen.FlatList`. Headers (and consumer UI) read it
-   * to animate on scroll.
-   */
+  /** Vertical scroll offset, updated on the UI thread for header animations. */
   scrollY: SharedValue<number>;
   /**
-   * Scroll distance (px) over which the active header collapses — measured by
-   * the header (e.g. large-title portal height, parallax hero height). `0`
-   * disables snap and collapse-range animations (`Header.Title` screens).
+   * Optional collapse distance for custom headers. Set via setHeaderCollapseHeight.
+   * Built-in headers derive their animation range from the theme.
    */
   headerCollapseHeight: SharedValue<number>;
   /**
-   * Native `snapToOffsets` for the scroll container. `[0, height]` when a
-   * collapsible header is active; `undefined` otherwise.
+   * Native list snap offsets set by setHeaderCollapseHeight. Undefined by default.
+   * For Screen.ScrollView, pass these explicitly as snapToOffsets.
    */
   headerSnapOffsets: number[] | undefined;
-  /** Updates collapse height for animations and native snap offsets. */
+  /** Rounds the height and sets `[0, height]` snap offsets; nonpositive heights clear snapping. */
   setHeaderCollapseHeight: (height: number) => void;
-  /** Shared scroll container ref — bound by `Screen.ScrollView` / `Screen.FlatList`. */
+  /**
+   * Ref bound by ScrollView and FlatList containers, including `Screen.List`
+   * with FlatList. Custom list implementations do not bind this ref.
+   * Its declared ScrollView type does not expose FlatList-specific methods.
+   */
   scrollRef: ScreenScrollRef;
   /** Scroll handler that mirrors offset into `scrollY`. */
   scrollHandler: ScrollHandlerProcessed<Record<string, unknown>>;
 
+  /** Resolved background color shared with scroll containers. */
   background?: string;
 }
 
 export const ScreenContext = createContext<ScreenContextValue | null>(null);
 
+/** Internal provider inputs resolved by the Screen root. */
 export interface ScreenScrollProviderProps {
   children: ReactNode;
-  /** Which axes scroll containers pad with `layout.screen.margin`. Default `'all'`. */
-  margins?: ScreenMargins;
+  /** Which axes scroll containers pad with `layout.screen.padding`. Default `'all'`. */
+  contentPadding?: ScreenContentPadding;
+  safeArea?: ScreenSafeArea;
   /** Whether a `Screen.Header` child is present. Default false. */
   hasHeader?: boolean;
 
+  /** Resolved background color shared with scroll containers. */
   background?: string;
 }
 
 /**
  * Owns the screen's shared scroll ref, offset, snap offsets, and header collapse
- * metrics. Header variants call {@link ScreenContextValue.setHeaderCollapseHeight};
- * scroll containers bind the ref via {@link useScreen}.
+ * metrics. Scroll containers bind the ref via {@link useScreen}.
  */
 export function ScreenScrollProvider({
   background = "transparent",
   children,
-  margins = "all",
+  contentPadding = "all",
+  safeArea = "auto",
   hasHeader = false,
 }: ScreenScrollProviderProps) {
   const scrollY = useSharedValue(0);
@@ -98,7 +106,9 @@ export function ScreenScrollProvider({
   const value = useMemo<ScreenContextValue>(
     () => ({
       background,
-      margins,
+      contentPadding,
+      safeArea,
+      margins: contentPadding,
       hasHeader,
       scrollY,
       headerCollapseHeight,
@@ -109,7 +119,8 @@ export function ScreenScrollProvider({
     }),
     [
       background,
-      margins,
+      contentPadding,
+      safeArea,
       hasHeader,
       scrollY,
       headerCollapseHeight,
@@ -124,14 +135,23 @@ export function ScreenScrollProvider({
 }
 
 /**
- * Access the enclosing `Screen`'s shared scroll state, ref, and snap offsets.
+ * Reads the nearest `Screen`'s configuration, shared scroll state, and ref.
+ * Read `scrollY.value` in Reanimated worklets to animate without React renders.
+ * The ref belongs to the primary scroll container, not the screen root.
  *
  * @example
  * ```tsx
- * const { scrollY, scrollRef, headerSnapOffsets } = useScreen();
+ * function FadingContent() {
+ *   const { scrollY } = useScreen();
+ *   const style = useAnimatedStyle(() => ({
+ *     opacity: interpolate(scrollY.value, [0, 100], [1, 0], "clamp"),
+ *   }));
+ *   return <Animated.View style={style}>{content}</Animated.View>;
+ * }
  * ```
  *
- * @throws if called outside a `Screen`.
+ * @returns The nearest Screen's configuration and scroll state.
+ * @throws Error when called outside a Screen provider.
  */
 export function useScreen(): ScreenContextValue {
   const context = useContext(ScreenContext);

package/src/components/screen/ScreenFlatList.tsx

@@ -1,192 +1,6 @@
-import { type FlatListProps, type NativeScrollEvent, type NativeSyntheticEvent, View } from "react-native";
+import { ScreenList, type ScreenListProps } from "./ScreenList";
 
-import Animated, {
-  type AnimatedRef,
-  useAnimatedScrollHandler,
-  useComposedEventHandler,
-} from "react-native-reanimated";
-import { StyleSheet } from "react-native-unistyles";
-
-import { resolveScreenMargin } from "#theme/screen-margin";
-import { PortalHost } from "../portal";
-import { BottomSafeArea } from "./parts/BottomSafeArea";
-import { renderScreenPlaceholder } from "./parts/ScreenPlaceholder";
-import { SCREEN_HEADER_PORTAL_HOST, useScreen } from "./ScreenContext";
-import type { ScreenMargins, ScreenScrollableProps } from "./types";
-import { hasXMargin, hasYMargin, renderListHeader } from "./utils";
-
-/**
- * @deprecated Use {@link ScreenListProps} (`Screen.List`) instead —
- * `Screen.List` renders `FlatList` by default and binds the screen's shared
- * scroll ref exactly as `Screen.FlatList` does, but also lets a screen swap in
- * any other FlatList-shaped list (e.g. `FlashList`) via its `as` prop.
- */
-export interface ScreenFlatListProps<T>
-  extends Omit<FlatListProps<T>, "CellRendererComponent" | "horizontal">,
-    ScreenScrollableProps {
-  /**
-   * 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;
-}
-
-/**
- * `FlatList` variant of `Screen.ScrollView`: binds the screen's shared scroll
- * ref, mirrors offset into `scrollY`, hosts the portal target above the list,
- * and applies token-driven content padding.
- *
- * Shares `loading` / `LoadingComponent` / `EmptyComponent` / `margins` /
- * `horizontal` with `Screen.ScrollView`, so a screen can swap one container for
- * another without relearning its API.
- *
- * @deprecated Use {@link ScreenList} (`Screen.List`) instead — it renders
- * `FlatList` by default and behaves identically, but also accepts an `as`
- * prop for swapping in another list implementation later without changing
- * the surrounding API.
- *
- * @example
- * ```tsx
- * <Screen.FlatList data={items} renderItem={({ item }) => <Row item={item} />} />
- * ```
- *
- * @example Loading and empty placeholders
- * ```tsx
- * <Screen.FlatList
- *   data={items}
- *   loading={isLoading}
- *   EmptyComponent={<EmptyState icon="status.info" title="Nothing yet" fill />}
- *   renderItem={({ item }) => <Row item={item} />}
- * />
- * ```
- */
-export function ScreenFlatList<T>({
-  data,
-  style,
-  contentContainerStyle,
-  ListHeaderComponent,
-  ListFooterComponent,
-  ListEmptyComponent,
-  horizontal = false,
-  loading = false,
-  LoadingComponent,
-  EmptyComponent,
-  margins,
-  bottomInset,
-  onScroll,
-  ...rest
-}: ScreenFlatListProps<T>) {
-  const {
-    background,
-    scrollRef,
-    scrollHandler,
-    headerSnapOffsets,
-    margins: screenMargins,
-    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 placeholder = renderScreenPlaceholder({
-    loading,
-    LoadingComponent,
-    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 = (
-    <>
-      {/* `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)}>
-        <PortalHost name={SCREEN_HEADER_PORTAL_HOST} />
-      </View>
-      {renderListHeader(ListHeaderComponent)}
-    </>
-  );
-
-  return (
-    <Animated.FlatList
-      ref={scrollRef as unknown as AnimatedRef<Animated.FlatList<T>>}
-      data={loading ? [] : data}
-      style={[{ backgroundColor: background }, style]}
-      horizontal={horizontal}
-      contentInsetAdjustmentBehavior={hasHeader ? "never" : undefined}
-      contentContainerStyle={[styles.content(resolvedMargins, hasHeader, bottomInset), contentContainerStyle]}
-      ListHeaderComponent={headerComponent}
-      ListFooterComponent={footerComponent}
-      ListEmptyComponent={placeholder ?? ListEmptyComponent}
-      showsVerticalScrollIndicator={false}
-      scrollEventThrottle={16}
-      snapToOffsets={headerSnapOffsets}
-      {...rest}
-      onScroll={composedHandler}
-    />
-  );
-}
-
-// `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) => ({
-  scrollContent: {
-    flexGrow: 1,
-  },
-  content: (margins: ScreenMargins, hasHeader: boolean, bottomInset: number | undefined) => {
-    const { x: marginX, y: marginY } = resolveScreenMargin(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),
-    };
-  },
-  safeArea: {
-    height: runtime.insets.top,
-  },
-  headerWrapper: (margins: ScreenMargins) => {
-    const { x: marginX } = resolveScreenMargin(theme, runtime.breakpoint);
-    return {
-      marginHorizontal: hasXMargin(margins) ? -marginX : 0,
-    };
-  },
-}));
+/** @deprecated Use ScreenListProps. */
+export type ScreenFlatListProps<T> = ScreenListProps<T>;
+/** @deprecated Use Screen.List, which exposes the same native FlatList and ref. */
+export const ScreenFlatList: typeof ScreenList = ScreenList;