@expo/ui 58.0.5 → 58.0.7

package/src/jetpack-compose/LazyItems/index.tsx

@@ -0,0 +1,121 @@
+import { requireNativeView } from 'expo';
+import { Fragment, type ReactElement } from 'react';
+
+import {
+  useItemKeys,
+  useRecycledRows,
+  type RecycledSlotProps,
+  type RenderItem,
+  type WindowChangeEvent,
+} from '../../recycling/useRecycledRows';
+import { type ViewEvent } from '../../types';
+
+export interface LazyItemsProps<ItemT> {
+  /** Items to display. Replace the array when updating data. */
+  data: readonly ItemT[];
+  /** Returns a stable, unique string key, also used as the lazy list item key. */
+  keyExtractor: (item: ItemT, index: number) => string;
+  /**
+   * Renders a row. Wrap it in `useCallback`, or every row re-renders on each parent render.
+   * Recycled rows are reused for other items, so their local state (`useState`) carries over.
+   * Reset it when the item changes, or keep the state outside the row.
+   */
+  children: RenderItem<ItemT>;
+  /**
+   * Renders only the rows near the visible range and reuses them while scrolling. Set to `false` to
+   * render every row at once. Set it once; changing it remounts the rows.
+   * @default true
+   */
+  recycling?: boolean;
+  /**
+   * Extra rows to prepare on each side of the visible rows. Must be a non-negative integer.
+   * Ignored when `recycling` is `false`.
+   * @default 10
+   */
+  overscanCount?: number;
+  /**
+   * Placeholder size in dp along the scroll axis, until a row is measured. Must be positive.
+   * Measurements reset when the data changes. In `LazyColumn.Items` they also reset when the list
+   * width changes. Ignored when `recycling` is `false`.
+   * @default 64
+   */
+  estimatedItemSize?: number;
+}
+
+type NativeLazyItemsProps = ViewEvent<'onWindowChange', WindowChangeEvent> & {
+  itemKeys: string[];
+  revision: number;
+  estimatedItemSize: number;
+  children: ReactElement;
+};
+
+const LazyItemsNativeView: React.ComponentType<NativeLazyItemsProps> =
+  requireNativeView<NativeLazyItemsProps>('ExpoUI', 'LazyItemsView');
+const LazyItemsSlotNativeView: React.ComponentType<RecycledSlotProps> =
+  requireNativeView<RecycledSlotProps>('ExpoUI', 'LazyItemsSlotView');
+const LazyItemsPoolNativeView: React.ComponentType<{ children: ReactElement[] }> =
+  requireNativeView('ExpoUI', 'LazyItemsPoolView');
+
+/**
+ * A block of recycled rows inside `LazyColumn` or `LazyRow`, mirroring the Compose
+ * `items(count, key)` builder. Only a small pool of rows around the visible range is mounted,
+ * so large data sets stay cheap. Rows that are not ready yet show a placeholder of
+ * `estimatedItemSize`, or of the size last measured for that item.
+ *
+ * Mount it as a direct child of `LazyColumn` or `LazyRow`. Plain children of the same list stay
+ * single items, so static and recycled content can be mixed in order.
+ * @platform android
+ */
+export const LazyItems = createLazyItems('LazyColumn.Items');
+
+/**
+ * @hidden
+ * Creates the `Items` component of one lazy list, so its errors name that list.
+ */
+export function createLazyItems(componentName: string) {
+  function Items<ItemT>({ recycling = true, ...props }: LazyItemsProps<ItemT>) {
+    return recycling ? <RecycledItems {...props} /> : <StaticItems {...props} />;
+  }
+
+  // Each row is a plain child of the lazy list, so it becomes one lazy item.
+  function StaticItems<ItemT>({
+    data,
+    keyExtractor,
+    children: renderItem,
+  }: Omit<LazyItemsProps<ItemT>, 'recycling'>) {
+    const itemKeys = useItemKeys(componentName, data, keyExtractor);
+    return data.map((item, index) => (
+      <Fragment key={itemKeys[index]}>{renderItem({ item, index })}</Fragment>
+    ));
+  }
+
+  function RecycledItems<ItemT>({
+    data,
+    keyExtractor,
+    children: renderItem,
+    overscanCount,
+    estimatedItemSize = 64,
+  }: Omit<LazyItemsProps<ItemT>, 'recycling'>) {
+    const { itemKeys, revision, rows, onWindowChange } = useRecycledRows({
+      componentName,
+      Slot: LazyItemsSlotNativeView,
+      data,
+      keyExtractor,
+      renderItem,
+      overscanCount,
+      estimatedItemSize,
+    });
+
+    return (
+      <LazyItemsNativeView
+        itemKeys={itemKeys}
+        revision={revision}
+        estimatedItemSize={estimatedItemSize}
+        onWindowChange={({ nativeEvent }) => onWindowChange(nativeEvent)}>
+        <LazyItemsPoolNativeView>{rows}</LazyItemsPoolNativeView>
+      </LazyItemsNativeView>
+    );
+  }
+  Items.displayName = componentName;
+  return Items;
+}

package/src/jetpack-compose/LazyRow/index.tsx

@@ -2,6 +2,7 @@ import { requireNativeView } from 'expo';
 
 import type { ExpoModifier } from '../../types';
 import { type ContentPadding } from '../LazyColumn';
+import { createLazyItems } from '../LazyItems';
 import { createViewModifierEventListener } from '../modifiers/utils';
 
 export interface LazyRowProps {
@@ -56,3 +57,5 @@ function transformProps(props: LazyRowProps): NativeLazyRowProps {
 export function LazyRow(props: LazyRowProps) {
   return <LazyRowNativeView {...transformProps(props)} />;
 }
+
+LazyRow.Items = createLazyItems('LazyRow.Items');

package/src/jetpack-compose/index.ts

@@ -17,6 +17,7 @@ export * from './ExposedDropdownMenuBox';
 export * from './Divider';
 export * from './Host';
 export * from './LazyColumn';
+export { type LazyItemsProps } from './LazyItems';
 export * from './LazyRow';
 export * from './ListItem';
 export * from './RNHostView';

package/src/recycling/useRecycledRows.tsx

@@ -0,0 +1,200 @@
+import {
+  memo,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ComponentType,
+  type ReactElement,
+} from 'react';
+
+import { getSlotIndices, getWindow } from './window';
+
+/** Payload of the native event asking for the rows around the visible range. */
+export type WindowChangeEvent = { first: number; last: number; revision: number };
+
+/** Props of the native view that holds one recycled row. */
+export type RecycledSlotProps = {
+  itemKey: string;
+  index: number;
+  revision: number;
+  children: ReactElement;
+};
+
+/** Renders one row of the data set. */
+export type RenderItem<ItemT> = (info: { item: ItemT; index: number }) => ReactElement;
+
+type RecycledRowProps<ItemT> = Omit<RecycledSlotProps, 'children'> & {
+  Slot: ComponentType<RecycledSlotProps>;
+  item: ItemT;
+  renderItem: RenderItem<ItemT>;
+};
+
+// Skip unchanged rows when the window moves.
+const RecycledRow = memo(function RecycledRow<ItemT>({
+  Slot,
+  item,
+  index,
+  itemKey,
+  revision,
+  renderItem,
+}: RecycledRowProps<ItemT>) {
+  return (
+    <Slot itemKey={itemKey} index={index} revision={revision}>
+      {renderItem({ item, index })}
+    </Slot>
+  );
+}) as <ItemT>(props: RecycledRowProps<ItemT>) => ReactElement;
+
+export type RecycledRows = {
+  /** Keys of every item, so the native list can size and identify the full data set. */
+  itemKeys: string[];
+  /** Increases whenever the data changes, so late native events can be dropped. */
+  revision: number;
+  /** The pooled rows to mount, one per slot. */
+  rows: ReactElement[];
+  /** Applies a native window request. */
+  onWindowChange: (event: WindowChangeEvent) => void;
+  /** Whether a native event was sent for the data currently committed to native. */
+  isCurrentRevision: (revision: number) => boolean;
+};
+
+/**
+ * Returns one key per item. Keys follow `data` only: an inline `keyExtractor` changes identity on
+ * every parent render, and recomputing keys for it would bump the revision and re-render every row.
+ */
+export function useItemKeys<ItemT>(
+  componentName: string,
+  data: readonly ItemT[],
+  keyExtractor: (item: ItemT, index: number) => string
+): string[] {
+  const keyExtractorRef = useRef(keyExtractor);
+  keyExtractorRef.current = keyExtractor;
+  return useMemo(() => {
+    const keys = data.map((item, index) => keyExtractorRef.current(item, index));
+    if (keys.some((key) => typeof key !== 'string') || new Set(keys).size !== keys.length) {
+      throw new Error(`${componentName} keyExtractor must return a unique string for every item.`);
+    }
+    return keys;
+  }, [data]);
+}
+
+/**
+ * Keeps a fixed pool of rows centered on the range the native list asks for.
+ * Item `index` always renders in slot `index % capacity`, so moving the window
+ * only re-renders the slots whose item changed.
+ */
+export function useRecycledRows<ItemT>({
+  componentName,
+  Slot,
+  data,
+  keyExtractor,
+  renderItem,
+  overscanCount = 10,
+  estimatedItemSize = 64,
+}: {
+  /** Name used in error messages, for example `List.ForEach`. */
+  componentName: string;
+  /** Native view that holds one recycled row. */
+  Slot: ComponentType<RecycledSlotProps>;
+  data: readonly ItemT[];
+  keyExtractor: (item: ItemT, index: number) => string;
+  renderItem: RenderItem<ItemT>;
+  overscanCount?: number;
+  estimatedItemSize?: number;
+}): RecycledRows {
+  if (!Number.isSafeInteger(overscanCount) || overscanCount < 0) {
+    throw new Error(`${componentName} overscanCount must be a non-negative integer.`);
+  }
+  if (!Number.isFinite(estimatedItemSize) || estimatedItemSize <= 0) {
+    throw new Error(`${componentName} estimatedItemSize must be a positive finite number.`);
+  }
+  const itemKeys = useItemKeys(componentName, data, keyExtractor);
+  const [state, setState] = useState({
+    keys: itemKeys,
+    first: 0,
+    last: 0,
+    revision: 0,
+    capacity: 0,
+    overscanCount,
+  });
+  let current = state;
+  if (state.keys !== itemKeys) {
+    const previousKey = state.keys[state.first];
+    const anchor = previousKey === undefined ? 0 : Math.max(0, itemKeys.indexOf(previousKey));
+    current = {
+      ...state,
+      keys: itemKeys,
+      first: Math.min(anchor, Math.max(0, data.length - 1)),
+      last: Math.min(anchor + state.last - state.first, Math.max(0, data.length - 1)),
+      revision: state.revision + 1,
+    };
+  }
+  if (current.overscanCount !== overscanCount) {
+    current = { ...current, overscanCount, capacity: 0 };
+  }
+  if (current !== state) setState(current);
+  const { start, capacity } = getWindow(
+    data.length,
+    current.first,
+    current.last,
+    overscanCount,
+    current.capacity
+  );
+  const committedRevision = useRef(current.revision);
+  useLayoutEffect(() => {
+    committedRevision.current = current.revision;
+  }, [current.revision]);
+
+  const rows = getSlotIndices(start, capacity).map((index, slot) => {
+    const item = data[index];
+    const itemKey = itemKeys[index];
+    if (item === undefined || itemKey === undefined) {
+      throw new Error(`${componentName} could not resolve the item at index ${index}.`);
+    }
+    return (
+      <RecycledRow
+        key={slot}
+        Slot={Slot}
+        item={item}
+        index={index}
+        itemKey={itemKey}
+        revision={current.revision}
+        renderItem={renderItem}
+      />
+    );
+  });
+
+  return {
+    itemKeys,
+    revision: current.revision,
+    rows,
+    isCurrentRevision: (revision) => revision === committedRevision.current,
+    onWindowChange: (event) => {
+      if (
+        !Number.isSafeInteger(event.first) ||
+        !Number.isSafeInteger(event.last) ||
+        event.last < event.first
+      ) {
+        return;
+      }
+      setState((previous) => {
+        // Ignore requests from before a data change.
+        if (event.revision !== previous.revision) return previous;
+        const maximum = Math.max(0, previous.keys.length - 1);
+        const first = Math.max(0, Math.min(event.first, maximum));
+        const last = Math.max(first, Math.min(event.last, maximum));
+        const { capacity } = getWindow(
+          previous.keys.length,
+          first,
+          last,
+          previous.overscanCount,
+          previous.capacity
+        );
+        return first === previous.first && last === previous.last && capacity === previous.capacity
+          ? previous
+          : { ...previous, first, last, capacity };
+      });
+    },
+  };
+}

package/src/recycling/window.ts

@@ -0,0 +1,28 @@
+export function getWindow(
+  count: number,
+  first: number,
+  last: number,
+  overscanCount: number,
+  minCapacity = 0
+) {
+  if (count === 0) return { start: 0, capacity: 0 };
+  first = Math.max(0, Math.min(first, count - 1));
+  last = Math.max(first, Math.min(last, count - 1));
+  const start = Math.max(0, first - overscanCount);
+  const end = Math.min(count, last + 1 + overscanCount);
+  // Never shrink the pool: a stable capacity keeps `index % capacity` slot assignments stable.
+  // Grow it with headroom, because every growth re-renders the whole pool.
+  const needed = end - start;
+  let capacity = minCapacity;
+  if (needed > capacity) capacity = capacity === 0 ? needed : needed + overscanCount;
+  capacity = Math.min(count, capacity);
+  return { start: Math.min(start, count - capacity), capacity };
+}
+
+export function getSlotIndices(start: number, capacity: number): number[] {
+  if (capacity === 0) return [];
+  return Array.from(
+    { length: capacity },
+    (_, slot) => start + ((slot - (start % capacity) + capacity) % capacity)
+  );
+}

package/src/swift-ui/List/DataListForEach.tsx

@@ -0,0 +1,128 @@
+import { requireNativeView } from 'expo';
+import { type ReactElement } from 'react';
+
+import {
+  useRecycledRows,
+  type RecycledSlotProps,
+  type WindowChangeEvent,
+} from '../../recycling/useRecycledRows';
+import { type ViewEvent } from '../../types';
+import { createViewModifierEventListener } from '../modifiers/utils';
+import { type CommonViewModifierProps } from '../types';
+
+export interface ListForEachProps<ItemT> extends CommonViewModifierProps {
+  /** Called with deleted indices from this group's `data` array. */
+  onDelete?: (indices: number[]) => void;
+  /**
+   * Called with the source indices and the destination index. The destination index counts
+   * positions before the moved items are removed, so it can equal `data.length`.
+   */
+  onMove?: (sourceIndices: number[], destination: number) => void;
+  /** Items to display. Replace the array when updating data. */
+  data: readonly ItemT[];
+  /** Returns a stable, unique string key, also used for `List` selection. */
+  keyExtractor: (item: ItemT, index: number) => string;
+  /**
+   * Renders a row. When `recycling` is `true`, wrap it in `useCallback`, or every row
+   * re-renders on each parent render.
+   * Recycled rows are reused for other items, so their local state (`useState`) carries over.
+   * Reset it when the item changes, or keep the state outside the row.
+   */
+  children: (info: { item: ItemT; index: number }) => ReactElement;
+  /**
+   * Renders only the rows near the visible range and reuses them while scrolling. Set to `false` to
+   * render every row at once. Set it once; changing it remounts the rows.
+   * @default true
+   */
+  recycling?: boolean;
+  /**
+   * Extra rows to prepare on each side of the visible rows. Must be a non-negative integer.
+   * Ignored when `recycling` is `false`.
+   * @default 10
+   */
+  overscanCount?: number;
+  /**
+   * Placeholder height in points, excluding `List` insets, until a row is measured.
+   * Must be positive. Measurements reset when `data` or width changes.
+   * Ignored when `recycling` is `false`.
+   * @default 64
+   */
+  estimatedItemSize?: number;
+}
+
+type NativeProps = CommonViewModifierProps &
+  ViewEvent<'onWindowChange', WindowChangeEvent> &
+  ViewEvent<'onDelete', { indices: number[]; revision: number }> &
+  ViewEvent<'onMove', { sourceIndices: number[]; destination: number; revision: number }> & {
+    deleteEnabled: boolean;
+    moveEnabled: boolean;
+    itemKeys: string[];
+    revision: number;
+    estimatedItemSize: number;
+    children: ReactElement;
+  };
+
+const NativeList = requireNativeView<NativeProps>('ExpoUI', 'DataListForEachView');
+export const NativeSlot = requireNativeView<RecycledSlotProps>('ExpoUI', 'DataListForEachItemView');
+const NativePool = requireNativeView<{ children: ReactElement[] }>(
+  'ExpoUI',
+  'DataListForEachPoolView'
+);
+
+/**
+ * Renders a window of recycled rows inside List or Section.
+ * Rows show placeholders while JS prepares content. Native keys still cover the full data set.
+ * @platform ios
+ */
+export function DataListForEach<ItemT>({
+  data,
+  keyExtractor,
+  children: renderItem,
+  overscanCount,
+  estimatedItemSize = 64,
+  modifiers,
+  onDelete,
+  onMove,
+  ...props
+}: ListForEachProps<ItemT>) {
+  const { itemKeys, revision, rows, onWindowChange, isCurrentRevision } = useRecycledRows({
+    componentName: 'List.ForEach',
+    Slot: NativeSlot,
+    data,
+    keyExtractor,
+    renderItem,
+    overscanCount,
+    estimatedItemSize,
+  });
+
+  return (
+    <NativeList
+      {...props}
+      modifiers={modifiers}
+      {...(modifiers ? createViewModifierEventListener(modifiers) : undefined)}
+      deleteEnabled={!!onDelete}
+      moveEnabled={!!onMove}
+      onDelete={
+        onDelete
+          ? ({ nativeEvent }) => {
+              if (isCurrentRevision(nativeEvent.revision)) onDelete(nativeEvent.indices);
+            }
+          : undefined
+      }
+      onMove={
+        onMove
+          ? ({ nativeEvent }) => {
+              if (isCurrentRevision(nativeEvent.revision)) {
+                onMove(nativeEvent.sourceIndices, nativeEvent.destination);
+              }
+            }
+          : undefined
+      }
+      itemKeys={itemKeys}
+      revision={revision}
+      estimatedItemSize={estimatedItemSize}
+      onWindowChange={({ nativeEvent }) => onWindowChange(nativeEvent)}>
+      <NativePool>{rows}</NativePool>
+    </NativeList>
+  );
+}

package/src/swift-ui/List/ListForEach.tsx

@@ -1,7 +1,11 @@
 import { requireNativeView } from 'expo';
 
+import { useItemKeys } from '../../recycling/useRecycledRows';
 import { type ViewEvent } from '../../types';
 import { type CommonViewModifierProps } from '../types';
+import { DataListForEach, NativeSlot, type ListForEachProps } from './DataListForEach';
+
+export { type ListForEachProps };
 
 const ListForEachNativeView: React.ComponentType<NativeListForEachProps> =
   requireNativeView<NativeListForEachProps>('ExpoUI', 'ListForEachView');
@@ -14,21 +18,29 @@ type NativeListForEachProps = CommonViewModifierProps &
   DeleteEvent &
   MoveEvent & {
     children: React.ReactNode;
+    deleteEnabled: boolean;
+    moveEnabled: boolean;
   };
 
-export interface ListForEachProps extends CommonViewModifierProps {
+/**
+ * @deprecated Pass `data` and `keyExtractor`, and render each row from a `children` function.
+ */
+export interface ListForEachElementsProps extends CommonViewModifierProps {
+  data?: never;
+  keyExtractor?: never;
+  recycling?: never;
+  overscanCount?: never;
+  estimatedItemSize?: never;
   /**
    * The children elements to be rendered inside the `List.ForEach`.
    */
   children: React.ReactNode;
-
   /**
    * Callback triggered when items are deleted.
    * Receives an array of indices that were deleted.
    * @see Official [SwiftUI documentation](https://developer.apple.com/documentation/swiftui/dynamicviewcontent/ondelete(perform:)).
    */
   onDelete?: (indices: number[]) => void;
-
   /**
    * Callback triggered when items are moved.
    * Receives the source indices and destination index.
@@ -37,14 +49,33 @@ export interface ListForEachProps extends CommonViewModifierProps {
   onMove?: (sourceIndices: number[], destination: number) => void;
 }
 
+let warnedElements = false;
+
 /**
- * A compound component of `List` that enables item deletion and reordering.
- * This component must be used as a child of `List` (as `List.ForEach`).
+ * A group of rows inside `List`, with optional deletion and reordering.
+ * Pass `data` with `keyExtractor`, and render each row from a `children` function.
+ * Recycles rows unless `recycling` is `false`.
  */
-export function ListForEach({ children, onDelete, onMove, ...props }: ListForEachProps) {
+export function ListForEach<ItemT>(props: ListForEachProps<ItemT> | ListForEachElementsProps) {
+  if (props.data === undefined) {
+    if (__DEV__ && !warnedElements) {
+      warnedElements = true;
+      console.warn(
+        '[@expo/ui] Passing elements as List.ForEach children is deprecated. Pass `data` and `keyExtractor`, and render each row from a `children` function: `{({ item }) => <Row item={item} />}`.'
+      );
+    }
+    return <ChildrenListForEach {...props} />;
+  }
+  const { recycling = true, ...rest } = props;
+  return recycling ? <DataListForEach {...rest} /> : <StaticListForEach {...rest} />;
+}
+
+function ChildrenListForEach({ children, onDelete, onMove, ...props }: ListForEachElementsProps) {
   return (
     <ListForEachNativeView
       {...props}
+      deleteEnabled={!!onDelete}
+      moveEnabled={!!onMove}
       onDelete={onDelete ? ({ nativeEvent }) => onDelete(nativeEvent.indices) : undefined}
       onMove={
         onMove
@@ -55,3 +86,23 @@ export function ListForEach({ children, onDelete, onMove, ...props }: ListForEac
     </ListForEachNativeView>
   );
 }
+
+function StaticListForEach<ItemT>({
+  data,
+  keyExtractor,
+  children: renderItem,
+  overscanCount: _overscanCount,
+  estimatedItemSize: _estimatedItemSize,
+  ...props
+}: Omit<ListForEachProps<ItemT>, 'recycling'>) {
+  const itemKeys = useItemKeys('List.ForEach', data, keyExtractor);
+  return (
+    <ChildrenListForEach {...props}>
+      {data.map((item, index) => (
+        <NativeSlot key={itemKeys[index]} itemKey={itemKeys[index]!} index={index} revision={0}>
+          {renderItem({ item, index })}
+        </NativeSlot>
+      ))}
+    </ChildrenListForEach>
+  );
+}

package/src/swift-ui/List/index.tsx

@@ -5,7 +5,7 @@ import { createViewModifierEventListener } from '../modifiers/utils';
 import { type CommonViewModifierProps } from '../types';
 import { ListForEach } from './ListForEach';
 
-export { ListForEach, type ListForEachProps } from './ListForEach';
+export { ListForEach, type ListForEachProps, type ListForEachElementsProps } from './ListForEach';
 
 const ListNativeView: React.ComponentType<NativeListProps> = requireNativeView<NativeListProps>(
   'ExpoUI',