@expo/ui 58.0.6 → 58.0.8

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/jetpack-compose/modifiers/index.ts

@@ -454,10 +454,25 @@ export const onGloballyPositioned = (
  */
 export const testID = (tag: string) => createModifier('testID', { testID: tag });
 
+/**
+ * Options for the `semantics` modifier.
+ */
+export type SemanticsConfig = {
+  /**
+   * An autofill hint, such as `'email'` or `'password'`.
+   */
+  contentType?: string;
+  /**
+   * What accessibility services such as TalkBack announce for the element. Useful when the visible
+   * content does not read well aloud, as with an abbreviation or a glyph.
+   */
+  contentDescription?: string;
+};
+
 /**
  * Applies semantic properties. Wraps `Modifier.semantics { ... }`.
  */
-export const semantics = (params: { contentType?: string }) => createModifier('semantics', params);
+export const semantics = (params: SemanticsConfig) => createModifier('semantics', params);
 
 // =============================================================================
 // Clip Modifier & Shapes

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/swift-ui/List/DataListForEach.tsx

@@ -1,10 +1,14 @@
 import { requireNativeView } from 'expo';
-import { memo, useLayoutEffect, useMemo, useRef, useState, type ReactElement } from 'react';
+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';
-import { getSlotIndices, getWindow } from './window';
 
 export interface ListForEachProps<ItemT> extends CommonViewModifierProps {
   /** Called with deleted indices from this group's `data` array. */
@@ -46,9 +50,8 @@ export interface ListForEachProps<ItemT> extends CommonViewModifierProps {
   estimatedItemSize?: number;
 }
 
-type WindowEvent = { first: number; last: number; revision: number };
 type NativeProps = CommonViewModifierProps &
-  ViewEvent<'onWindowChange', WindowEvent> &
+  ViewEvent<'onWindowChange', WindowChangeEvent> &
   ViewEvent<'onDelete', { indices: number[]; revision: number }> &
   ViewEvent<'onMove', { sourceIndices: number[]; destination: number; revision: number }> & {
     deleteEnabled: boolean;
@@ -58,59 +61,14 @@ type NativeProps = CommonViewModifierProps &
     estimatedItemSize: number;
     children: ReactElement;
   };
-type SlotProps = {
-  itemKey: string;
-  index: number;
-  revision: number;
-  children: ReactElement;
-};
 
 const NativeList = requireNativeView<NativeProps>('ExpoUI', 'DataListForEachView');
-export const NativeSlot = requireNativeView<SlotProps>('ExpoUI', 'DataListForEachItemView');
+export const NativeSlot = requireNativeView<RecycledSlotProps>('ExpoUI', 'DataListForEachItemView');
 const NativePool = requireNativeView<{ children: ReactElement[] }>(
   'ExpoUI',
   'DataListForEachPoolView'
 );
 
-// Skip unchanged rows when the window moves.
-const RecycledRow = memo(function RecycledRow<ItemT>({
-  item,
-  index,
-  itemKey,
-  revision,
-  renderItem,
-}: SlotPropsWithoutChildren & {
-  item: ItemT;
-  renderItem: ListForEachProps<ItemT>['children'];
-}) {
-  return (
-    <NativeSlot itemKey={itemKey} index={index} revision={revision}>
-      {renderItem({ item, index })}
-    </NativeSlot>
-  );
-}) as <ItemT>(
-  props: SlotPropsWithoutChildren & {
-    item: ItemT;
-    renderItem: ListForEachProps<ItemT>['children'];
-  }
-) => ReactElement;
-type SlotPropsWithoutChildren = Omit<SlotProps, 'children'>;
-
-export function useItemKeys<ItemT>(
-  data: readonly ItemT[],
-  keyExtractor: ListForEachProps<ItemT>['keyExtractor']
-): 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('List.ForEach keyExtractor must return a unique string for every item.');
-    }
-    return keys;
-  }, [data]);
-}
-
 /**
  * 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.
@@ -120,56 +78,22 @@ export function DataListForEach<ItemT>({
   data,
   keyExtractor,
   children: renderItem,
-  overscanCount = 10,
+  overscanCount,
   estimatedItemSize = 64,
   modifiers,
   onDelete,
   onMove,
   ...props
 }: ListForEachProps<ItemT>) {
-  if (!Number.isSafeInteger(overscanCount) || overscanCount < 0) {
-    throw new Error('List.ForEach overscanCount must be a non-negative integer.');
-  }
-  if (!Number.isFinite(estimatedItemSize) || estimatedItemSize <= 0) {
-    throw new Error('List.ForEach estimatedItemSize must be a positive finite number.');
-  }
-  const itemKeys = useItemKeys(data, keyExtractor);
-  const [state, setState] = useState({
-    keys: itemKeys,
-    first: 0,
-    last: 0,
-    revision: 0,
-    capacity: 0,
+  const { itemKeys, revision, rows, onWindowChange, isCurrentRevision } = useRecycledRows({
+    componentName: 'List.ForEach',
+    Slot: NativeSlot,
+    data,
+    keyExtractor,
+    renderItem,
     overscanCount,
+    estimatedItemSize,
   });
-  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 indices = getSlotIndices(start, capacity);
 
   return (
     <NativeList
@@ -181,69 +105,24 @@ export function DataListForEach<ItemT>({
       onDelete={
         onDelete
           ? ({ nativeEvent }) => {
-              if (nativeEvent.revision === committedRevision.current) onDelete(nativeEvent.indices);
+              if (isCurrentRevision(nativeEvent.revision)) onDelete(nativeEvent.indices);
             }
           : undefined
       }
       onMove={
         onMove
           ? ({ nativeEvent }) => {
-              if (nativeEvent.revision === committedRevision.current) {
+              if (isCurrentRevision(nativeEvent.revision)) {
                 onMove(nativeEvent.sourceIndices, nativeEvent.destination);
               }
             }
           : undefined
       }
       itemKeys={itemKeys}
-      revision={current.revision}
+      revision={revision}
       estimatedItemSize={estimatedItemSize}
-      onWindowChange={({ nativeEvent: 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 };
-        });
-      }}>
-      <NativePool>
-        {indices.map((index, slot) => {
-          const item = data[index];
-          const itemKey = itemKeys[index];
-          if (item === undefined || itemKey === undefined) {
-            throw new Error(`List.ForEach could not resolve the item at index ${index}.`);
-          }
-          return (
-            <RecycledRow
-              key={slot}
-              item={item}
-              index={index}
-              itemKey={itemKey}
-              revision={current.revision}
-              renderItem={renderItem}
-            />
-          );
-        })}
-      </NativePool>
+      onWindowChange={({ nativeEvent }) => onWindowChange(nativeEvent)}>
+      <NativePool>{rows}</NativePool>
     </NativeList>
   );
 }

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

@@ -1,8 +1,9 @@
 import { requireNativeView } from 'expo';
 
+import { useItemKeys } from '../../recycling/useRecycledRows';
 import { type ViewEvent } from '../../types';
 import { type CommonViewModifierProps } from '../types';
-import { DataListForEach, NativeSlot, useItemKeys, type ListForEachProps } from './DataListForEach';
+import { DataListForEach, NativeSlot, type ListForEachProps } from './DataListForEach';
 
 export { type ListForEachProps };
 
@@ -94,7 +95,7 @@ function StaticListForEach<ItemT>({
   estimatedItemSize: _estimatedItemSize,
   ...props
 }: Omit<ListForEachProps<ItemT>, 'recycling'>) {
-  const itemKeys = useItemKeys(data, keyExtractor);
+  const itemKeys = useItemKeys('List.ForEach', data, keyExtractor);
   return (
     <ChildrenListForEach {...props}>
       {data.map((item, index) => (

package/src/swift-ui/modifiers/index.ts

@@ -106,7 +106,11 @@ export const matchedGeometryEffect = (
  */
 export const geometryGroup = () => createModifier('geometryGroup', {});
 
-type FrameAlignment =
+/**
+ * The alignment of a view inside the frame that `frame()` creates.
+ * Most values have no visible effect when the frame is the same size as the view.
+ */
+export type FrameAlignment =
   | 'center'
   | 'leading'
   | 'trailing'

package/src/swift-ui/modifiers/presentationModifiers.ts

@@ -57,6 +57,16 @@ export const presentationDetents = (
 export const presentationDragIndicator = (visibility: 'automatic' | 'visible' | 'hidden') =>
   createModifier('presentationDragIndicator', { visibility });
 
+/**
+ * Sets the corner radius of a sheet presentation.
+ * @param cornerRadius - The corner radius in points, or `null` to use the system default.
+ * @platform ios 16.4+
+ * @platform tvos 16.4+
+ * @see Official [SwiftUI documentation](https://developer.apple.com/documentation/swiftui/view/presentationcornerradius(_:)).
+ */
+export const presentationCornerRadius = (cornerRadius: number | null) =>
+  createModifier('presentationCornerRadius', { cornerRadius });
+
 /**
  * Presentation background interaction type.
  */

package/src/universal/State.android.ts

@@ -1,3 +1,3 @@
 export { useNativeState } from '@expo/ui/jetpack-compose';
 
-export type ObservableState<T> = { value: T };
+export type { ObservableState } from './types';

package/src/universal/State.ios.ts

@@ -1,3 +1,3 @@
 export { useNativeState } from '@expo/ui/swift-ui';
 
-export type ObservableState<T> = { value: T };
+export type { ObservableState } from './types';