@expo/ui 56.0.8 → 56.0.9

package/src/universal/Host/types.ts

@@ -0,0 +1,70 @@
+import type { ColorSchemeName, ViewProps } from 'react-native';
+
+/**
+ * Props for the [`Host`](#host) component.
+ */
+export interface UniversalHostProps extends ViewProps {
+  /**
+   * When `true`, the host updates its size in the React Native view tree to match the content's layout from the underlying platform UI toolkit.
+   * Can only be set once on mount.
+   *
+   * @default false
+   * @platform android
+   * @platform ios
+   * @platform web
+   */
+  matchContents?: boolean | { vertical?: boolean; horizontal?: boolean };
+
+  /**
+   * The color scheme to apply to descendant native views.
+   * `'light'` / `'dark'` force a specific appearance; omitted follows the device setting.
+   *
+   * @platform android
+   * @platform ios
+   */
+  colorScheme?: ColorSchemeName;
+
+  /**
+   * Layout direction for the platform UI content.
+   * Defaults to the current locale direction from `I18nManager`.
+   *
+   * @platform android
+   * @platform ios
+   * @platform web
+   */
+  layoutDirection?: 'leftToRight' | 'rightToLeft';
+
+  /**
+   * Controls which safe area regions the hosting view should ignore. Can only be set once on mount.
+   * - `'all'`- ignores all safe area insets.
+   * - `'keyboard'` - ignores only the keyboard safe area.
+   *
+   * @platform android
+   * @platform ios
+   * @platform web
+   */
+  ignoreSafeArea?: 'all' | 'keyboard';
+
+  /**
+   * When true and no explicit size is provided, the host will use the viewport size as the proposed size for layout.
+   * This is particularly useful for views that need to fill their available space, such as `List`.
+   * @default false
+   *
+   * @platform android
+   * @platform ios
+   * @platform web
+   */
+  useViewportSizeMeasurement?: boolean;
+
+  /**
+   * Callback function that is triggered when the content completes its layout.
+   * Provides the current dimensions of the content, which may change as the content updates.
+   *
+   * @platform android
+   * @platform ios
+   * @platform web
+   */
+  onLayoutContent?: (event: { nativeEvent: { width: number; height: number } }) => void;
+
+  children?: React.ReactNode;
+}

package/src/universal/List/index.android.tsx

@@ -0,0 +1,44 @@
+import { LazyColumn, PullToRefreshBox } from '@expo/ui/jetpack-compose';
+import { testID as testIDModifier, type ModifierConfig } from '@expo/ui/jetpack-compose/modifiers';
+import { useCallback, useState } from 'react';
+
+import type { ListProps } from './types';
+
+/**
+ * Android implementation of `List`.
+ * Composes `LazyColumn` and wraps with `PullToRefreshBox` when `onRefresh` is provided.
+ * The returned promise drives the refresh indicator's visibility.
+ */
+export function List({ children, onRefresh, testID }: ListProps) {
+  const [isRefreshing, setIsRefreshing] = useState(false);
+
+  const handleRefresh = useCallback(async () => {
+    if (!onRefresh) return;
+    setIsRefreshing(true);
+    try {
+      await onRefresh();
+    } finally {
+      setIsRefreshing(false);
+    }
+  }, [onRefresh]);
+
+  const listModifiers: ModifierConfig[] | undefined = testID ? [testIDModifier(testID)] : undefined;
+  const listContent = <LazyColumn modifiers={listModifiers}>{children}</LazyColumn>;
+
+  if (!onRefresh) {
+    return listContent;
+  }
+
+  return (
+    // `contentAlignment="topCenter"` keeps the refresh indicator centered.
+    // The indicator's own `Modifier.align` resolves outside `BoxScope` and becomes a no-op, so we set it on the parent.
+    <PullToRefreshBox
+      isRefreshing={isRefreshing}
+      onRefresh={handleRefresh}
+      contentAlignment="topCenter">
+      {listContent}
+    </PullToRefreshBox>
+  );
+}
+
+export * from './types';

package/src/universal/List/index.ios.tsx

@@ -0,0 +1,19 @@
+import { List as SwiftUIList } from '@expo/ui/swift-ui';
+import { refreshable, type ModifierConfig } from '@expo/ui/swift-ui/modifiers';
+
+import type { ListProps } from './types';
+
+/**
+ * iOS implementation of `List`.
+ * Delegates to SwiftUI's `List` and applies `.refreshable` when `onRefresh` is provided.
+ */
+export function List({ children, onRefresh, testID }: ListProps) {
+  const modifiers: ModifierConfig[] | undefined = onRefresh ? [refreshable(onRefresh)] : undefined;
+  return (
+    <SwiftUIList modifiers={modifiers} testID={testID}>
+      {children}
+    </SwiftUIList>
+  );
+}
+
+export * from './types';

package/src/universal/List/index.tsx

@@ -0,0 +1,26 @@
+import { StyleSheet, View } from 'react-native';
+
+import type { ListProps } from './types';
+
+/**
+ * A vertical container of rows.
+ * Typically populated with [`ListItem`](#listitem) children.
+ */
+export function List({ children, testID }: ListProps) {
+  return (
+    <View style={styles.container} testID={testID}>
+      {children}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flexDirection: 'column',
+    width: '100%',
+    overflowX: 'auto',
+    overflowY: 'auto',
+  },
+});
+
+export * from './types';

package/src/universal/List/types.ts

@@ -0,0 +1,28 @@
+import type { ReactNode } from 'react';
+
+/**
+ * Props for the [`List`](#list) component.
+ * A virtualized vertical container of rows.
+ * Typically populated with [`ListItem`](#listitem) children, though any node is accepted.
+ */
+export interface ListProps {
+  /**
+   * The list rows. Usually `<ListItem>` elements.
+   */
+  children?: ReactNode;
+
+  /**
+   * Optional pull-to-refresh handler.
+   * When provided, the list shows the platform-native refresh affordance.
+   * The returned promise drives the indicator's visibility.
+   *
+   * @platform android
+   * @platform ios
+   */
+  onRefresh?: () => Promise<void>;
+
+  /**
+   * Identifier used to locate the component in end-to-end tests.
+   */
+  testID?: string;
+}

package/src/universal/ListItem/ListItem.android.tsx

@@ -0,0 +1,52 @@
+import { ListItem as ComposeListItem, Text } from '@expo/ui/jetpack-compose';
+import { clickable } from '@expo/ui/jetpack-compose/modifiers';
+import { Children, type ReactNode } from 'react';
+
+import { extractListItemSlots } from './ListItemSlots';
+import type { ListItemProps } from './types';
+
+// Compose hosts can't render raw strings — they need a `Text` composable.
+// Wrap any string/number node so consumers can pass plain strings via shorthand props or compound children.
+function wrapStrings(node: ReactNode): ReactNode {
+  if (node == null || typeof node === 'boolean') return node;
+  if (typeof node === 'string' || typeof node === 'number') return <Text>{node}</Text>;
+  if (Array.isArray(node)) return Children.map(node, wrapStrings);
+  return node;
+}
+
+/**
+ * Android implementation of `ListItem`.
+ * Delegates to Material 3 `ListItem` and applies `clickable` for tap handling.
+ */
+export function ListItem(props: ListItemProps) {
+  const { children, onPress, leading: leadingProp, trailing: trailingProp, supportingText } = props;
+  const slots = extractListItemSlots(children);
+  const leading = slots.leading ?? leadingProp;
+  const trailing = slots.trailing ?? trailingProp;
+  const supporting = slots.supporting ?? supportingText;
+
+  return (
+    <ComposeListItem modifiers={onPress ? [clickable(onPress)] : undefined}>
+      <ComposeListItem.HeadlineContent>
+        <>{wrapStrings(slots.headline)}</>
+      </ComposeListItem.HeadlineContent>
+      {supporting != null ? (
+        <ComposeListItem.SupportingContent>
+          {typeof supporting === 'string' || typeof supporting === 'number' ? (
+            <Text>{supporting}</Text>
+          ) : (
+            supporting
+          )}
+        </ComposeListItem.SupportingContent>
+      ) : null}
+      {leading != null ? (
+        <ComposeListItem.LeadingContent>{wrapStrings(leading)}</ComposeListItem.LeadingContent>
+      ) : null}
+      {trailing != null ? (
+        <ComposeListItem.TrailingContent>{wrapStrings(trailing)}</ComposeListItem.TrailingContent>
+      ) : null}
+    </ComposeListItem>
+  );
+}
+
+export * from './types';

package/src/universal/ListItem/ListItem.ios.tsx

@@ -0,0 +1,58 @@
+import { Button, HStack, Spacer, Text, VStack } from '@expo/ui/swift-ui';
+import { buttonStyle, contentShape, foregroundStyle, shapes } from '@expo/ui/swift-ui/modifiers';
+import { Children, type ReactNode } from 'react';
+
+import { extractListItemSlots } from './ListItemSlots';
+import type { ListItemProps } from './types';
+
+// Wrap raw strings/numbers in a SwiftUI `Text` — SwiftUI hosts can't render bare strings.
+function wrapStrings(node: ReactNode): ReactNode {
+  if (node == null || typeof node === 'boolean') return node;
+  if (typeof node === 'string' || typeof node === 'number') return <Text>{node}</Text>;
+  if (Array.isArray(node)) return Children.map(node, wrapStrings);
+  return node;
+}
+
+function renderSupporting(node: ReactNode): ReactNode {
+  if (typeof node === 'string' || typeof node === 'number') {
+    return (
+      <Text modifiers={[foregroundStyle({ type: 'color', color: 'secondaryLabel' })]}>{node}</Text>
+    );
+  }
+  return node;
+}
+
+/**
+ * iOS implementation of `ListItem`.
+ * Wraps a plain SwiftUI `Button` and applies `contentShape(.rectangle())` so the full row rectangle registers taps, including the gap between slots.
+ */
+export function ListItem(props: ListItemProps) {
+  const {
+    children,
+    onPress,
+    leading: leadingProp,
+    trailing: trailingProp,
+    supportingText,
+    testID,
+  } = props;
+  const slots = extractListItemSlots(children);
+  const leading = slots.leading ?? leadingProp;
+  const trailing = slots.trailing ?? trailingProp;
+  const supporting = slots.supporting ?? supportingText;
+
+  return (
+    <Button onPress={onPress} modifiers={[buttonStyle('plain')]} testID={testID}>
+      <HStack alignment="center" spacing={12} modifiers={[contentShape(shapes.rectangle())]}>
+        {wrapStrings(leading)}
+        <VStack alignment="leading" spacing={2}>
+          <>{wrapStrings(slots.headline)}</>
+          {supporting != null ? renderSupporting(supporting) : null}
+        </VStack>
+        <Spacer />
+        {wrapStrings(trailing)}
+      </HStack>
+    </Button>
+  );
+}
+
+export * from './types';

package/src/universal/ListItem/ListItem.tsx

@@ -0,0 +1,72 @@
+import type { ReactNode } from 'react';
+import { Pressable, StyleSheet, Text, View } from 'react-native';
+
+import { extractListItemSlots } from './ListItemSlots';
+import type { ListItemProps } from './types';
+
+function renderSupporting(node: ReactNode): ReactNode {
+  if (typeof node === 'string') {
+    return <Text style={styles.supportingText}>{node}</Text>;
+  }
+  return node;
+}
+
+/**
+ * A tappable row in a list.
+ * Composes with [`List`](#list).
+ * Pass row content via the `leading` / `trailing` / `supportingText` shorthand props or the compound `<ListItem.Leading>` / `<ListItem.Trailing>` / `<ListItem.Supporting>` slot children.
+ */
+export function ListItem(props: ListItemProps) {
+  const {
+    children,
+    onPress,
+    leading: leadingProp,
+    trailing: trailingProp,
+    supportingText,
+    testID,
+  } = props;
+  const slots = extractListItemSlots(children);
+  const leading = slots.leading ?? leadingProp;
+  const trailing = slots.trailing ?? trailingProp;
+  const supporting = slots.supporting ?? supportingText;
+
+  return (
+    <Pressable onPress={onPress} style={styles.row} testID={testID}>
+      {leading != null ? <View style={styles.slot}>{leading}</View> : null}
+      <View style={styles.main}>
+        <Text>{slots.headline}</Text>
+        {supporting != null ? renderSupporting(supporting) : null}
+      </View>
+      {trailing != null ? <View style={styles.slot}>{trailing}</View> : null}
+    </Pressable>
+  );
+}
+
+const styles = StyleSheet.create({
+  row: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: 12,
+    width: '100%',
+    paddingVertical: 12,
+    paddingHorizontal: 16,
+    cursor: 'pointer',
+  },
+  main: {
+    flexDirection: 'column',
+    gap: 2,
+    flex: 1,
+    minWidth: 0,
+  },
+  slot: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    flexShrink: 0,
+  },
+  supportingText: {
+    fontSize: 13,
+    color: '#6b7280',
+  },
+});
+
+export * from './types';

package/src/universal/ListItem/ListItemSlots.tsx

@@ -0,0 +1,66 @@
+import { Children, Fragment, isValidElement, type ReactNode } from 'react';
+
+import type { ListItemLeadingProps, ListItemSupportingProps, ListItemTrailingProps } from './types';
+
+/** Leading-slot marker for [`ListItem`](#listitem). */
+export function Leading(props: ListItemLeadingProps) {
+  return props.children;
+}
+
+/** Trailing-slot marker for [`ListItem`](#listitem). */
+export function Trailing(props: ListItemTrailingProps) {
+  return props.children;
+}
+
+/** Supporting-text-slot marker for [`ListItem`](#listitem), rendered below the headline. */
+export function Supporting(props: ListItemSupportingProps) {
+  return props.children;
+}
+
+export type ExtractedListItemSlots = {
+  leading?: ReactNode;
+  trailing?: ReactNode;
+  supporting?: ReactNode;
+  headline: ReactNode[];
+};
+
+/**
+ * Walks `children`, pulls out any `<ListItem.Leading>` /
+ * `<ListItem.Trailing>` / `<ListItem.Supporting>` slots, and returns the
+ * remaining nodes as the headline content. Recurses into `React.Fragment`.
+ */
+export function extractListItemSlots(children: ReactNode): ExtractedListItemSlots {
+  let leading: ReactNode | undefined;
+  let trailing: ReactNode | undefined;
+  let supporting: ReactNode | undefined;
+  const headline: ReactNode[] = [];
+
+  const walk = (node: ReactNode) => {
+    Children.forEach(node, (child) => {
+      if (!isValidElement(child)) {
+        headline.push(child);
+        return;
+      }
+      if (child.type === Leading) {
+        leading = (child.props as { children?: ReactNode }).children;
+        return;
+      }
+      if (child.type === Trailing) {
+        trailing = (child.props as { children?: ReactNode }).children;
+        return;
+      }
+      if (child.type === Supporting) {
+        supporting = (child.props as { children?: ReactNode }).children;
+        return;
+      }
+      if (child.type === Fragment) {
+        walk((child.props as { children?: ReactNode }).children);
+        return;
+      }
+      headline.push(child);
+    });
+  };
+
+  walk(children);
+  return { leading, trailing, supporting, headline };
+}

package/src/universal/ListItem/index.ts

@@ -0,0 +1,15 @@
+import { ListItem as ListItemBase } from './ListItem';
+import { Leading, Supporting, Trailing } from './ListItemSlots';
+import type { ListItemLeadingProps, ListItemSupportingProps, ListItemTrailingProps } from './types';
+
+const ListItem = ListItemBase as typeof ListItemBase & {
+  Leading: React.FC<ListItemLeadingProps>;
+  Trailing: React.FC<ListItemTrailingProps>;
+  Supporting: React.FC<ListItemSupportingProps>;
+};
+ListItem.Leading = Leading;
+ListItem.Trailing = Trailing;
+ListItem.Supporting = Supporting;
+
+export { ListItem };
+export * from './types';

package/src/universal/ListItem/types.ts

@@ -0,0 +1,67 @@
+import type { ReactNode } from 'react';
+
+/**
+ * Props for the [`ListItem.Leading`](#listitemleading) slot marker.
+ */
+export interface ListItemLeadingProps {
+  /** Content rendered in the leading (start) slot. */
+  children?: ReactNode;
+}
+
+/**
+ * Props for the [`ListItem.Trailing`](#listitemtrailing) slot marker.
+ */
+export interface ListItemTrailingProps {
+  /** Content rendered in the trailing (end) slot. */
+  children?: ReactNode;
+}
+
+/**
+ * Props for the [`ListItem.Supporting`](#listitemsupporting) slot marker.
+ */
+export interface ListItemSupportingProps {
+  /** Content rendered below the headline. */
+  children?: ReactNode;
+}
+
+/**
+ * Props for the [`ListItem`](#listitem) component.
+ * A tappable row in a list.
+ */
+export interface ListItemProps {
+  /**
+   * Headline content of the row.
+   * The remaining (non-slot) children are rendered in the headline area.
+   */
+  children?: ReactNode;
+
+  /**
+   * Tap handler.
+   * Activates over the entire row rectangle, including the empty gap between leading/headline/trailing.
+   */
+  onPress?: () => void;
+
+  /**
+   * Shorthand for the leading slot.
+   * Overridden by `<ListItem.Leading>` if both are provided.
+   */
+  leading?: ReactNode;
+
+  /**
+   * Shorthand for the trailing slot.
+   * Overridden by `<ListItem.Trailing>` if both are provided.
+   */
+  trailing?: ReactNode;
+
+  /**
+   * Shorthand for the supporting (sub-)text slot.
+   * Strings are rendered with platform-appropriate secondary styling; pass a `ReactNode` for richer content.
+   * Overridden by `<ListItem.Supporting>` if both are provided.
+   */
+  supportingText?: string | ReactNode;
+
+  /**
+   * Identifier used to locate the component in end-to-end tests.
+   */
+  testID?: string;
+}

package/src/universal/Picker/Picker.android.tsx

@@ -0,0 +1,69 @@
+import { useEffect, useRef, useState } from 'react';
+
+import { extractPickerItems } from './PickerItem';
+import type { PickerItemValue, PickerProps } from './types';
+import { DropdownMenuItem } from '../../jetpack-compose/DropdownMenu/DropdownMenuItem';
+import {
+  ExposedDropdownMenuBox,
+  ExposedDropdownMenu,
+} from '../../jetpack-compose/ExposedDropdownMenuBox';
+import { Text } from '../../jetpack-compose/Text';
+import { TextField, type TextFieldRef } from '../../jetpack-compose/TextField';
+import { menuAnchor, onVisibilityChanged } from '../../jetpack-compose/modifiers';
+
+/**
+ * Android implementation of `Picker`.
+ * Renders a Material 3 `ExposedDropdownMenuBox`.
+ * `appearance` is accepted for API parity but ignored — Material 3 has no wheel-style picker.
+ */
+export function Picker<T extends PickerItemValue>({
+  selectedValue,
+  onValueChange,
+  enabled = true,
+  children,
+}: PickerProps<T>) {
+  const items = extractPickerItems<T>(children);
+  const [expanded, setExpanded] = useState(false);
+  const [isVisible, setIsVisible] = useState(false);
+  const textFieldRef = useRef<TextFieldRef>(null);
+
+  const selectedLabel = items.find((item) => item.value === selectedValue)?.label ?? '';
+  // The anchor `TextField` is uncontrolled — push the current label imperatively once the view is on screen.
+  useEffect(() => {
+    if (!isVisible) return;
+    textFieldRef.current?.setText(selectedLabel);
+  }, [selectedLabel, isVisible]);
+
+  return (
+    <ExposedDropdownMenuBox
+      expanded={expanded}
+      onExpandedChange={enabled ? setExpanded : undefined}>
+      <TextField
+        ref={textFieldRef}
+        readOnly
+        enabled={enabled}
+        modifiers={[menuAnchor(), onVisibilityChanged((visible) => setIsVisible(visible))]}
+      />
+      <ExposedDropdownMenu expanded={expanded} onDismissRequest={() => setExpanded(false)}>
+        {items.map((item) => (
+          <DropdownMenuItem
+            key={String(item.value)}
+            onClick={
+              enabled
+                ? () => {
+                    onValueChange(item.value);
+                    setExpanded(false);
+                  }
+                : undefined
+            }>
+            <DropdownMenuItem.Text>
+              <Text>{item.label}</Text>
+            </DropdownMenuItem.Text>
+          </DropdownMenuItem>
+        ))}
+      </ExposedDropdownMenu>
+    </ExposedDropdownMenuBox>
+  );
+}
+
+export * from './types';

package/src/universal/Picker/Picker.ios.tsx

@@ -0,0 +1,45 @@
+import { Picker as SwiftUIPicker, Text } from '@expo/ui/swift-ui';
+import {
+  disabled as disabledModifier,
+  pickerStyle,
+  tag,
+  type ModifierConfig,
+} from '@expo/ui/swift-ui/modifiers';
+
+import { extractPickerItems } from './PickerItem';
+import type { PickerItemValue, PickerProps } from './types';
+
+/**
+ * iOS implementation of `Picker`.
+ * Wraps SwiftUI's `Picker` and applies the matching `.pickerStyle` for the requested `appearance`.
+ * Embed inside a parent `<Host>` (same as `Column` / `Row`).
+ */
+export function Picker<T extends PickerItemValue>({
+  selectedValue,
+  onValueChange,
+  appearance = 'menu',
+  enabled = true,
+  children,
+  testID,
+}: PickerProps<T>) {
+  const items = extractPickerItems<T>(children);
+  const swiftUIStyle = appearance === 'wheel' ? 'wheel' : 'menu';
+  const modifiers: ModifierConfig[] = [pickerStyle(swiftUIStyle)];
+  if (!enabled) modifiers.push(disabledModifier(true));
+
+  return (
+    <SwiftUIPicker
+      selection={selectedValue}
+      onSelectionChange={(value) => onValueChange(value as T)}
+      modifiers={modifiers}
+      testID={testID}>
+      {items.map((item) => (
+        <Text key={String(item.value)} modifiers={[tag(item.value)]}>
+          {item.label}
+        </Text>
+      ))}
+    </SwiftUIPicker>
+  );
+}
+
+export * from './types';