@expo/ui 56.0.8 → 56.0.10

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

@@ -1,7 +1,6 @@
 import type { UnitPointValue } from '.';
 import { createModifier, createModifierWithEventListener } from './createModifier';
-import { type ObservableState } from '../../State/useNativeState';
-import { getStateId } from '../../State/utils';
+import { getStateId, type ObservableState } from '../../State';
 
 /**
  * Attaches a stable identifier to a view so it can be referenced by scroll target bindings.

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

@@ -1,6 +1,5 @@
 import { createModifier } from './createModifier';
-import { type ObservableState } from '../../State/useNativeState';
-import { getStateId } from '../../State/utils';
+import { getStateId, type ObservableState } from '../../State';
 
 // https://developer.apple.com/documentation/symbols/appearsymboleffect
 type AppearSymbolEffect = {

package/src/swift-ui/withAnimation.ts

@@ -0,0 +1,71 @@
+import { requireNativeModule } from 'expo';
+
+import { worklets } from '../State';
+import { VALUE_SYMBOL } from './modifiers/animation/constants';
+import type { AnimationObject, ChainableAnimationType } from './modifiers/animation/types';
+
+const ExpoUI = requireNativeModule('ExpoUI');
+
+/**
+ * @see Official [SwiftUI documentation](https://developer.apple.com/documentation/swiftui/animationcompletioncriteria).
+ */
+export type WithAnimationCompletionCriteria = 'logicallyComplete' | 'removed';
+
+/**
+ * Mirrors SwiftUI's [`withAnimation(_:_:)`](https://developer.apple.com/documentation/swiftui/withanimation(_:_:)).
+ * The body must be a worklet so the mutations run synchronously on the
+ * UI thread inside the animation transaction.
+ *
+ * Performs `body` inside a SwiftUI animation transaction. Any
+ * `useNativeState` values mutated by the worklet animate to their new value
+ * using `animation`.
+ *
+ * @param animation Animation to apply, built with the `Animation` factory
+ * from `@expo/ui/swift-ui/modifiers`. Pass `null` to run `body` without an
+ * animation.
+ * @param body Worklet that mutates one or more `useNativeState` values.
+ * @param completion Optional worklet invoked on the main thread when the
+ * animation finishes. Requires iOS 17 / tvOS 17; on earlier versions the
+ * animation still runs but the callback is silently skipped.
+ * @param completionCriteria Controls when `completion` fires. Defaults to
+ * `'logicallyComplete'`.
+ */
+export function withAnimation(
+  animation: ChainableAnimationType | null,
+  body: () => void,
+  completion?: () => void,
+  completionCriteria?: WithAnimationCompletionCriteria
+): void {
+  if (!worklets) {
+    throw new Error(
+      "withAnimation needs the 'react-native-worklets' package, which couldn't be loaded. " +
+        'Install react-native-worklets and rebuild the native app, then call withAnimation again.'
+    );
+  }
+
+  if (!worklets.isWorkletFunction(body)) {
+    throw new Error(
+      'withAnimation body must be a worklet. Worklets run synchronously on the UI thread ' +
+        "so state changes are captured by SwiftUI's animation transaction. " +
+        "Add the 'worklet' directive as the first statement: " +
+        "() => { 'worklet'; state.value = next; }."
+    );
+  }
+
+  let completionCallback: object | null = null;
+  if (completion) {
+    if (!worklets.isWorkletFunction(completion)) {
+      throw new Error(
+        "withAnimation completion must be a worklet. Add the 'worklet' directive as the " +
+          'first statement in your completion callback.'
+      );
+    }
+    completionCallback = new ExpoUI.WorkletCallback(worklets.createSerializable(completion));
+  }
+
+  const animationObject: AnimationObject | null =
+    animation == null ? null : animation[VALUE_SYMBOL]();
+
+  const bodyCallback = new ExpoUI.WorkletCallback(worklets.createSerializable(body));
+  ExpoUI.withAnimation(animationObject, bodyCallback, completionCallback, completionCriteria);
+}

package/src/ts-declarations/react-native-web.d.ts

@@ -7,6 +7,7 @@ declare module 'react-native' {
   ) => React.ReactElement<P>;
 
   type DisplayValue = ReactNative.FlexStyle['display'] | 'inline-flex';
+  type OverflowValue = 'auto' | 'hidden' | 'scroll' | 'visible';
   type WebDimensionValue = ReactNative.DimensionValue | string;
 
   type WebRole =
@@ -104,6 +105,8 @@ declare module 'react-native' {
     display?: DisplayValue;
     height?: WebDimensionValue;
     width?: WebDimensionValue;
+    overflowX?: OverflowValue;
+    overflowY?: OverflowValue;
     paddingLeft?: WebDimensionValue;
     paddingRight?: WebDimensionValue;
     paddingTop?: WebDimensionValue;
@@ -114,6 +117,8 @@ declare module 'react-native' {
     display?: DisplayValue;
     height?: WebDimensionValue;
     width?: WebDimensionValue;
+    overflowX?: OverflowValue;
+    overflowY?: OverflowValue;
     paddingLeft?: WebDimensionValue;
     paddingRight?: WebDimensionValue;
     paddingTop?: WebDimensionValue;
@@ -124,6 +129,8 @@ declare module 'react-native' {
     display?: DisplayValue;
     height?: WebDimensionValue;
     width?: WebDimensionValue;
+    overflowX?: OverflowValue;
+    overflowY?: OverflowValue;
     paddingLeft?: WebDimensionValue;
     paddingRight?: WebDimensionValue;
     paddingTop?: WebDimensionValue;

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

@@ -1,34 +1,81 @@
-import { Column, ModalBottomSheet } from '@expo/ui/jetpack-compose';
+import { Column, Host, ModalBottomSheet, type ModalBottomSheetRef } from '@expo/ui/jetpack-compose';
 import {
+  fillMaxHeight,
   padding,
   testID as testIDModifier,
   type ModifierConfig,
 } from '@expo/ui/jetpack-compose/modifiers';
+import { useEffect, useRef, useState } from 'react';
 
-import type { BottomSheetProps } from './types';
+import type { BottomSheetProps, SnapPoint } from './types';
+
+// M3 `ModalBottomSheet` only has partial/expanded states.
+// Only allow the partial state when the consumer requested a partial-friendly snap point.
+function shouldSkipPartiallyExpanded(snapPoints: SnapPoint[] | undefined): boolean {
+  if (!snapPoints || snapPoints.length === 0) return false;
+  return !snapPoints.some(
+    (sp) =>
+      sp === 'half' ||
+      (typeof sp === 'object' && 'fraction' in sp && sp.fraction < 1) ||
+      (typeof sp === 'object' && 'height' in sp)
+  );
+}
+
+// M3 sizes content to intrinsic height.
+// Apply `fillMaxHeight` so `'full'` actually fills the viewport instead of stopping at content height.
+function shouldFillMaxHeight(snapPoints: SnapPoint[] | undefined): boolean {
+  if (!snapPoints || snapPoints.length === 0) return false;
+  return snapPoints.some(
+    (sp) => sp === 'full' || (typeof sp === 'object' && 'fraction' in sp && sp.fraction >= 1)
+  );
+}
 
 export function BottomSheet({
   children,
   isPresented,
   onDismiss,
   showDragIndicator = true,
+  snapPoints,
   testID,
   modifiers,
 }: BottomSheetProps) {
-  if (!isPresented) return null;
+  const sheetRef = useRef<ModalBottomSheetRef>(null);
+  const [mount, setMount] = useState(isPresented);
+
+  useEffect(() => {
+    if (isPresented) {
+      setMount(true);
+      return;
+    }
+    let cancelled = false;
+    sheetRef.current?.hide().then(() => {
+      if (!cancelled) setMount(false);
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [isPresented]);
+
+  if (!mount) {
+    return null;
+  }
 
   const contentModifiers: ModifierConfig[] = [padding(16, showDragIndicator ? 0 : 16, 16, 0)];
+  if (shouldFillMaxHeight(snapPoints)) contentModifiers.push(fillMaxHeight());
   if (testID) contentModifiers.push(testIDModifier(testID));
 
   return (
-    <ModalBottomSheet
-      onDismissRequest={onDismiss}
-      showDragHandle={showDragIndicator}
-      modifiers={modifiers}>
-      {/* When the drag handle is hidden, add top padding so content doesn't
-          crop against the top edge of the sheet. */}
-      <Column modifiers={contentModifiers}>{children}</Column>
-    </ModalBottomSheet>
+    <Host style={{ position: 'absolute' }} pointerEvents="none">
+      <ModalBottomSheet
+        ref={sheetRef}
+        onDismissRequest={onDismiss}
+        showDragHandle={showDragIndicator}
+        skipPartiallyExpanded={shouldSkipPartiallyExpanded(snapPoints)}
+        modifiers={modifiers}>
+        {/* When the drag handle is hidden, add top padding so content doesn't crop against the top edge of the sheet. */}
+        <Column modifiers={contentModifiers}>{children}</Column>
+      </ModalBottomSheet>
+    </Host>
   );
 }
 

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

@@ -1,34 +1,54 @@
-import { BottomSheet as SwiftUIBottomSheet, Group } from '@expo/ui/swift-ui';
-import { frame, padding, presentationDragIndicator } from '@expo/ui/swift-ui/modifiers';
+import { BottomSheet as SwiftUIBottomSheet, Group, Host } from '@expo/ui/swift-ui';
+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
-      testID={testID}>
-      <Group
-        modifiers={[
-          frame({ maxWidth: Infinity, alignment: 'topLeading' }),
-          padding({ top: 16, leading: 16, trailing: 16 }),
-          presentationDragIndicator(showDragIndicator ? 'visible' : 'hidden'),
-          ...(modifiers ?? []),
-        ]}>
-        {children}
-      </Group>
-    </SwiftUIBottomSheet>
+    <Host style={{ position: 'absolute' }} pointerEvents="none">
+      <SwiftUIBottomSheet
+        isPresented={isPresented}
+        onIsPresentedChange={(presented) => {
+          if (!presented) onDismiss();
+        }}
+        fitToContents={!snapPoints || snapPoints.length === 0}
+        testID={testID}>
+        <Group modifiers={presentationModifiers}>{children}</Group>
+      </SwiftUIBottomSheet>
+    </Host>
   );
 }
 

package/src/universal/BottomSheet/index.tsx

@@ -1,6 +1,27 @@
+import { useColorScheme } from 'react-native';
 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 +31,34 @@ export function BottomSheet({
   isPresented,
   onDismiss,
   showDragIndicator = true,
+  snapPoints,
   testID,
 }: BottomSheetProps) {
+  const isDark = useColorScheme() === 'dark';
+  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,
+            ...(isDark && { backgroundColor: '#000' }),
+            // 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 +85,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/Checkbox/index.tsx

@@ -1,5 +1,12 @@
 import type { ComponentProps } from 'react';
-import { StyleSheet, Text, unstable_createElement, View, type ViewProps } from 'react-native';
+import {
+  StyleSheet,
+  Text,
+  unstable_createElement,
+  useColorScheme,
+  View,
+  type ViewProps,
+} from 'react-native';
 
 import type { CheckboxProps } from './types';
 
@@ -19,6 +26,9 @@ const styles = StyleSheet.create({
     // @ts-expect-error
     cursor: 'inherit',
   },
+  darkText: {
+    color: '#fff',
+  },
 });
 
 const NativeCheckbox = (
@@ -29,6 +39,8 @@ const NativeCheckbox = (
  * A toggle control that represents a checked or unchecked state.
  */
 export function Checkbox({ value, onValueChange, label, disabled = false, testID }: CheckboxProps) {
+  const isDark = useColorScheme() === 'dark';
+
   return (
     <View role="label" aria-disabled={disabled} style={[styles.label, disabled && styles.disabled]}>
       <NativeCheckbox
@@ -38,7 +50,7 @@ export function Checkbox({ value, onValueChange, label, disabled = false, testID
         data-testid={testID}
         style={styles.cursorInherit}
       />
-      {label != null && <Text>{label}</Text>}
+      {label != null && <Text style={isDark && styles.darkText}>{label}</Text>}
     </View>
   );
 }

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,71 @@
+import type { ComponentProps, SyntheticEvent } from 'react';
+import {
+  StyleSheet,
+  Text,
+  unstable_createElement,
+  useColorScheme,
+  View,
+  type TextProps,
+  type ViewProps,
+} from 'react-native';
+
+import type { CollapsibleProps } from './types';
+
+const Details = (
+  props: Omit<ComponentProps<'details'>, 'style'> & { style?: TextProps['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) {
+  const isDark = useColorScheme() === 'dark';
+
+  return (
+    <Details
+      open={isOpen}
+      onToggle={(event: SyntheticEvent<HTMLDetailsElement>) => {
+        const nextOpen = event.currentTarget.open;
+        if (nextOpen !== isOpen) {
+          onOpenChange(nextOpen);
+        }
+      }}
+      style={[styles.container, isDark && styles.darkText]}>
+      <Summary style={styles.summary}>
+        <Text style={isDark && styles.darkText}>{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,
+  },
+  darkText: {
+    color: '#fff',
+  },
+});
+
+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,