@expo/ui 56.0.7 → 56.0.9

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

@@ -1,33 +1,51 @@
 import { BottomSheet as SwiftUIBottomSheet, Group } from '@expo/ui/swift-ui';
-import { frame, padding, presentationDragIndicator } from '@expo/ui/swift-ui/modifiers';
+import {
+  frame,
+  padding,
+  presentationDetents,
+  presentationDragIndicator,
+  type ModifierConfig,
+  type PresentationDetent,
+} from '@expo/ui/swift-ui/modifiers';
 
-import type { BottomSheetProps } from './types';
+import type { BottomSheetProps, SnapPoint } from './types';
+
+function snapPointToDetent(snapPoint: SnapPoint): PresentationDetent {
+  if (snapPoint === 'half') return 'medium';
+  if (snapPoint === 'full') return 'large';
+  return snapPoint;
+}
 
 export function BottomSheet({
   children,
   isPresented,
   onDismiss,
   showDragIndicator = true,
+  snapPoints,
   testID,
   modifiers,
 }: BottomSheetProps) {
+  const presentationModifiers: ModifierConfig[] = [
+    frame({ maxWidth: Infinity, alignment: 'topLeading' }),
+    padding({ top: 16, leading: 16, trailing: 16 }),
+    presentationDragIndicator(showDragIndicator ? 'visible' : 'hidden'),
+  ];
+  if (snapPoints && snapPoints.length > 0) {
+    presentationModifiers.push(presentationDetents(snapPoints.map(snapPointToDetent)));
+  }
+  if (modifiers?.length) {
+    presentationModifiers.push(...modifiers);
+  }
+
   return (
     <SwiftUIBottomSheet
       isPresented={isPresented}
       onIsPresentedChange={(presented) => {
         if (!presented) onDismiss();
       }}
-      fitToContents
+      fitToContents={!snapPoints || snapPoints.length === 0}
       testID={testID}>
-      <Group
-        modifiers={[
-          frame({ maxWidth: Infinity, alignment: 'topLeading' }),
-          padding({ top: 16, leading: 16, trailing: 16 }),
-          presentationDragIndicator(showDragIndicator ? 'visible' : 'hidden'),
-          ...(modifiers ?? []),
-        ]}>
-        {children}
-      </Group>
+      <Group modifiers={presentationModifiers}>{children}</Group>
     </SwiftUIBottomSheet>
   );
 }

package/src/universal/BottomSheet/index.tsx

@@ -1,6 +1,26 @@
 import { Drawer } from 'vaul';
 
-import type { BottomSheetProps } from './types';
+import type { BottomSheetProps, SnapPoint } from './types';
+
+// Visually-hidden style for the screen-reader-only Drawer.Title.
+const visuallyHiddenStyle: React.CSSProperties = {
+  position: 'absolute',
+  width: 1,
+  height: 1,
+  padding: 0,
+  margin: -1,
+  overflow: 'hidden',
+  clip: 'rect(0, 0, 0, 0)',
+  whiteSpace: 'nowrap',
+  border: 0,
+};
+
+function snapPointToVaul(snapPoint: SnapPoint): string | number {
+  if (snapPoint === 'half') return 0.5;
+  if (snapPoint === 'full') return 1;
+  if ('fraction' in snapPoint) return snapPoint.fraction;
+  return `${snapPoint.height}px`;
+}
 
 /**
  * A modal sheet that slides up from the bottom of the screen.
@@ -10,17 +30,32 @@ export function BottomSheet({
   isPresented,
   onDismiss,
   showDragIndicator = true,
+  snapPoints,
   testID,
 }: BottomSheetProps) {
+  const vaulSnapPoints = snapPoints?.length ? snapPoints.map(snapPointToVaul) : undefined;
+  const hasSnapPoints = vaulSnapPoints != null;
+
   return (
     <Drawer.Root
       open={isPresented}
       onOpenChange={(open) => {
         if (!open) onDismiss();
-      }}>
+      }}
+      snapPoints={vaulSnapPoints}>
       <Drawer.Portal>
         <Drawer.Overlay style={overlayStyle} />
-        <Drawer.Content style={{ ...contentStyle, ...(showDragIndicator && dragIndicatorSpacing) }}>
+        <Drawer.Content
+          style={{
+            ...contentStyle,
+            // Snap-points mode: vaul translates the drawer by `viewport - snapHeight`.
+            // The drawer has to fill the viewport or it gets pushed off-screen.
+            ...(hasSnapPoints ? snapPointContentStyle : noSnapPointContentStyle),
+            ...(showDragIndicator && dragIndicatorSpacing),
+          }}
+          aria-describedby={undefined}>
+          {/* Radix Dialog requires a title for a11y; render visually-hidden. */}
+          <Drawer.Title style={visuallyHiddenStyle}>Bottom sheet</Drawer.Title>
           {showDragIndicator && <Drawer.Handle />}
           <div style={innerStyle} data-testid={testID}>
             {children}
@@ -47,12 +82,19 @@ const contentStyle: React.CSSProperties = {
   borderTopLeftRadius: 16,
   borderTopRightRadius: 16,
   zIndex: 50,
-  maxHeight: '85vh',
   outline: 'none',
   display: 'flex',
   flexDirection: 'column',
 };
 
+const snapPointContentStyle: React.CSSProperties = {
+  height: '96vh',
+};
+
+const noSnapPointContentStyle: React.CSSProperties = {
+  maxHeight: '85vh',
+};
+
 const innerStyle: React.CSSProperties = {
   padding: 16,
   overflow: 'auto',

package/src/universal/BottomSheet/types.ts

@@ -1,5 +1,20 @@
 import type { ModifierConfig } from '../../types';
 
+/**
+ * A snap point describing one of the heights a [`BottomSheet`](#bottomsheet) can rest at.
+ *
+ * - `'half'` — Approximately half-screen.
+ * - `'full'` — Fully expanded.
+ * - `{ fraction }` — A fraction of the screen height (0–1).
+ *   iOS / web only.
+ * - `{ height }` — A fixed pixel height.
+ *   iOS / web only.
+ *
+ * On Android, `{ fraction }` and `{ height }` snap to the nearest of `'half'` / `'full'`.
+ * See the component docs for platform behavior notes.
+ */
+export type SnapPoint = 'half' | 'full' | { fraction: number } | { height: number };
+
 /**
  * Props for the [`BottomSheet`](#bottomsheet) component, a modal sheet that slides up from the bottom of the screen.
  */
@@ -25,6 +40,16 @@ export interface BottomSheetProps {
    */
   showDragIndicator?: boolean;
 
+  /**
+   * Heights the sheet can rest at.
+   * When omitted, the sheet auto-sizes to its content.
+   * See [`SnapPoint`](#snappoint) for the supported values.
+   *
+   * @example `['half', 'full']` — draggable between half and full
+   * @example `['full']` — always full height
+   */
+  snapPoints?: SnapPoint[];
+
   /**
    * Identifier used to locate the component in end-to-end tests.
    */

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

@@ -0,0 +1,72 @@
+import {
+  AnimatedVisibility,
+  Column,
+  EnterTransition,
+  ExitTransition,
+  Icon,
+  ListItem,
+  Text,
+  useMaterialColors,
+} from '@expo/ui/jetpack-compose';
+import {
+  animated,
+  background,
+  clickable,
+  clip,
+  graphicsLayer,
+  padding,
+  Shapes,
+  spring,
+} from '@expo/ui/jetpack-compose/modifiers';
+
+import type { CollapsibleProps } from './types';
+
+const KEYBOARD_ARROW_DOWN = require('../../../assets/keyboard_arrow_down.xml');
+
+// M3 large-corner token (16dp) — the Expressive expandable-list-item pattern.
+const CONTAINER_SHAPE = Shapes.RoundedCorner(16);
+
+// expandVertically + fadeIn keeps motion strictly vertical.
+// (Compose's default expandIn includes a horizontal component.)
+const ENTER = EnterTransition.expandVertically().plus(EnterTransition.fadeIn());
+const EXIT = ExitTransition.shrinkVertically().plus(ExitTransition.fadeOut());
+
+/**
+ * Android implementation of `Collapsible`.
+ * A rounded M3 card whose container tint fades between `transparent` (collapsed) and `surfaceContainer` (expanded).
+ */
+export function Collapsible({ isOpen, onOpenChange, label = '', children }: CollapsibleProps) {
+  const colors = useMaterialColors();
+  const containerColor = isOpen ? colors.surfaceContainer : 'transparent';
+
+  return (
+    <Column
+      modifiers={[
+        // `clip` first so background paint and the inner ListItem's ripple both respect the rounded shape.
+        clip(CONTAINER_SHAPE),
+        background(containerColor, { animationSpec: spring() }),
+      ]}>
+      <ListItem
+        // Transparent so the outer `background` is the sole tint source.
+        colors={{ containerColor: 'transparent' }}
+        modifiers={[clickable(() => onOpenChange(!isOpen))]}>
+        <ListItem.HeadlineContent>
+          <Text>{label}</Text>
+        </ListItem.HeadlineContent>
+        <ListItem.TrailingContent>
+          <Icon
+            source={KEYBOARD_ARROW_DOWN}
+            modifiers={[graphicsLayer({ rotationZ: animated(isOpen ? 180 : 0, spring()) })]}
+          />
+        </ListItem.TrailingContent>
+      </ListItem>
+      <AnimatedVisibility visible={isOpen} enterTransition={ENTER} exitTransition={EXIT}>
+        {/* 16dp matches the M3 large-corner radius.
+            ListItem's own bottom padding adds the M3 header–body separation on top. */}
+        <Column modifiers={[padding(16, 16, 16, 16)]}>{children}</Column>
+      </AnimatedVisibility>
+    </Column>
+  );
+}
+
+export * from './types';

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

@@ -0,0 +1,16 @@
+import { DisclosureGroup } from '@expo/ui/swift-ui';
+
+import type { CollapsibleProps } from './types';
+
+/**
+ * iOS implementation of `Collapsible`. Wraps SwiftUI's `DisclosureGroup`.
+ */
+export function Collapsible({ isOpen, onOpenChange, label = '', children }: CollapsibleProps) {
+  return (
+    <DisclosureGroup label={label} isExpanded={isOpen} onIsExpandedChange={onOpenChange}>
+      {children}
+    </DisclosureGroup>
+  );
+}
+
+export * from './types';

package/src/universal/Collapsible/index.tsx

@@ -0,0 +1,58 @@
+import type { ComponentProps, SyntheticEvent } from 'react';
+import { StyleSheet, Text, unstable_createElement, View, type ViewProps } from 'react-native';
+
+import type { CollapsibleProps } from './types';
+
+const Details = (
+  props: Omit<ComponentProps<'details'>, 'style'> & { style?: ViewProps['style'] }
+) => unstable_createElement('details', props);
+
+const Summary = (
+  props: Omit<ComponentProps<'summary'>, 'style'> & { style?: ViewProps['style'] }
+) => unstable_createElement('summary', props);
+
+/**
+ * A primitive that toggles visibility of its content via a labelled tappable
+ * header. Controlled via `isOpen` + `onOpenChange`.
+ */
+export function Collapsible({ isOpen, onOpenChange, label = '', children }: CollapsibleProps) {
+  return (
+    <Details
+      open={isOpen}
+      onToggle={(event: SyntheticEvent<HTMLDetailsElement>) => {
+        const nextOpen = event.currentTarget.open;
+        if (nextOpen !== isOpen) {
+          onOpenChange(nextOpen);
+        }
+      }}
+      style={styles.container}>
+      <Summary style={styles.summary}>
+        <Text>{label}</Text>
+      </Summary>
+      <View style={styles.content}>{children}</View>
+    </Details>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    flexDirection: 'column',
+    width: '100%',
+  },
+  summary: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: 8,
+    width: '100%',
+    paddingHorizontal: 16,
+    paddingVertical: 12,
+    userSelect: 'none',
+    cursor: 'pointer',
+  },
+  content: {
+    paddingHorizontal: 16,
+    paddingBottom: 12,
+  },
+});
+
+export * from './types';

package/src/universal/Collapsible/types.ts

@@ -0,0 +1,25 @@
+/**
+ * Props for the [`Collapsible`](#collapsible) component, a primitive that
+ * shows or hides its content with a tap on a labelled header.
+ */
+export interface CollapsibleProps {
+  /**
+   * Whether the content is currently expanded.
+   */
+  isOpen: boolean;
+
+  /**
+   * Called when the user taps the header to toggle the open state.
+   */
+  onOpenChange: (isOpen: boolean) => void;
+
+  /**
+   * Text rendered in the tappable header.
+   */
+  label?: string;
+
+  /**
+   * Content rendered when `isOpen` is `true`.
+   */
+  children?: React.ReactNode;
+}

package/src/universal/Column/index.tsx

@@ -5,7 +5,9 @@ import { useUniversalLifecycle } from '../hooks';
 import type { UniversalAlignment } from '../types';
 
 const styles = StyleSheet.create({
-  column: { flexDirection: 'column' },
+  // `alignSelf: 'stretch'` — match SwiftUI `VStack` / Compose `Column`, which fill their parent's cross-axis.
+  // Without this, a nested Column inherits its parent's `alignItems` (often `flex-start`) and shrinks to content.
+  column: { flexDirection: 'column', alignSelf: 'stretch' },
   hidden: { display: 'none' },
   disabled: {
     opacity: 0.5,

package/src/universal/Host/index.tsx

@@ -1,18 +1,82 @@
-import { View, type ViewProps } from 'react-native';
+import { StyleSheet, View, type LayoutChangeEvent } from 'react-native';
+
+import type { UniversalHostProps } from './types';
+
+const styles = StyleSheet.create({
+  matchContents: {
+    alignSelf: 'flex-start',
+  },
+  matchViewport: {
+    height: '100dvh',
+    width: '100dvw',
+  },
+  safeArea: {
+    paddingLeft: 'max(env(safe-area-inset-left, 0px), env(keyboard-inset-left, 0px))',
+    paddingRight: 'max(env(safe-area-inset-right, 0px), env(keyboard-inset-right, 0px))',
+    paddingTop: 'max(env(safe-area-inset-top, 0px), env(keyboard-inset-top, 0px))',
+    paddingBottom: 'max(env(safe-area-inset-bottom, 0px), env(keyboard-inset-bottom, 0px))',
+  },
+  safeAreaWithoutKeyboard: {
+    paddingLeft: 'env(safe-area-inset-left, 0px)',
+    paddingRight: 'env(safe-area-inset-right, 0px)',
+    paddingTop: 'env(safe-area-inset-top, 0px)',
+    paddingBottom: 'env(safe-area-inset-bottom, 0px)',
+  },
+});
 
 /**
  * A bridging container that hosts SwiftUI views on iOS and Jetpack Compose views on Android.
+ * On platforms without a native UI-toolkit binding (web, RN fallback), renders a plain `View`.
+ * The `colorScheme`, `layoutDirection`, and `matchContents` props are accepted for API parity but have no effect.
  */
 export function Host({
   children,
+  ignoreSafeArea,
+  layoutDirection,
+  matchContents = false,
+  onLayout,
+  onLayoutContent,
   style,
+  useViewportSizeMeasurement = false,
+  colorScheme: _colorScheme,
   ...rest
-}: ViewProps & {
-  matchContents?: boolean | { vertical?: boolean; horizontal?: boolean };
-}) {
+}: UniversalHostProps) {
+  const shouldMatchContents =
+    typeof matchContents === 'object'
+      ? matchContents.horizontal || matchContents.vertical
+      : matchContents;
+
   return (
-    <View style={style} {...rest}>
+    <View
+      dir={
+        layoutDirection === 'leftToRight'
+          ? 'ltr'
+          : layoutDirection === 'rightToLeft'
+            ? 'rtl'
+            : undefined
+      }
+      onLayout={(event: LayoutChangeEvent) => {
+        onLayout?.(event);
+
+        onLayoutContent?.({
+          nativeEvent: {
+            width: event.nativeEvent.layout.width,
+            height: event.nativeEvent.layout.height,
+          },
+        });
+      }}
+      style={[
+        ignoreSafeArea !== 'all' &&
+          (ignoreSafeArea === 'keyboard' ? styles.safeAreaWithoutKeyboard : styles.safeArea),
+        shouldMatchContents
+          ? styles.matchContents
+          : useViewportSizeMeasurement && styles.matchViewport,
+        style,
+      ]}
+      {...rest}>
       {children}
     </View>
   );
 }
+
+export type { UniversalHostProps } from './types';

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;
+}