@expo/ui 56.0.7 → 56.0.9

package/src/community/menu/MenuView.ios.tsx

@@ -0,0 +1,149 @@
+import * as React from 'react';
+
+import type { MenuAction, MenuComponentProps, MenuComponentRef, NativeActionEvent } from './types';
+import { Button } from '../../swift-ui/Button';
+import { ContextMenu } from '../../swift-ui/ContextMenu';
+import { Host } from '../../swift-ui/Host';
+import { Menu } from '../../swift-ui/Menu';
+import { RNHostView } from '../../swift-ui/RNHostView';
+import { Section } from '../../swift-ui/Section';
+import { Toggle } from '../../swift-ui/Toggle';
+import {
+  disabled as disabledModifier,
+  foregroundColor as foregroundColorModifier,
+  tint as tintModifier,
+} from '../../swift-ui/modifiers';
+import type { ModifierConfig } from '../../types';
+
+function actionId(action: MenuAction): string {
+  return action.id ?? action.title;
+}
+
+function makeEvent(action: MenuAction): NativeActionEvent {
+  return { nativeEvent: { event: actionId(action) } };
+}
+
+function renderAction(
+  action: MenuAction,
+  onPressAction: MenuComponentProps['onPressAction']
+): React.ReactNode {
+  if (action.attributes?.hidden) {
+    return null;
+  }
+
+  const { subactions, displayInline, state, attributes, image, imageColor, title } = action;
+  const key = actionId(action);
+  const systemImage = typeof image === 'string' ? image : undefined;
+  // `tint` is what SwiftUI's `Menu`/`Button` honor for the leading SF Symbol —
+  // `foregroundColor` would also affect the label text.
+  const tintMod = imageColor ? tintModifier(imageColor) : null;
+
+  if (subactions && subactions.length > 0) {
+    const children = subactions.map((sub) => renderAction(sub, onPressAction));
+    if (displayInline) {
+      return (
+        <Section key={key} title={title}>
+          {children}
+        </Section>
+      );
+    }
+    // SwiftUI's system menu UI ignores per-item color modifiers on submenu
+    // headers, so we don't forward `imageColor` here. Leaf `Button`s below
+    // tint via `foregroundColor`, which does take effect.
+    return (
+      <Menu key={key} label={title} systemImage={systemImage}>
+        {children}
+      </Menu>
+    );
+  }
+
+  const fire = () => onPressAction?.(makeEvent(action));
+
+  const modifiers: ModifierConfig[] = [];
+  if (attributes?.disabled) modifiers.push(disabledModifier(true));
+
+  if (state === 'on' || state === 'off') {
+    if (tintMod) modifiers.push(tintMod);
+    return (
+      <Toggle
+        key={key}
+        label={title}
+        systemImage={systemImage}
+        isOn={state === 'on'}
+        onIsOnChange={fire}
+        modifiers={modifiers.length > 0 ? modifiers : undefined}
+      />
+    );
+  }
+
+  // For a leaf `Button`, `foregroundColor` also tints the system image —
+  // upstream uses this to color both the label and the icon. Skip when the
+  // role is destructive so SwiftUI's red tint remains in effect.
+  if (imageColor && !attributes?.destructive) {
+    modifiers.push(foregroundColorModifier(imageColor));
+  }
+
+  return (
+    <Button
+      key={key}
+      label={title}
+      systemImage={systemImage}
+      role={attributes?.destructive ? 'destructive' : undefined}
+      modifiers={modifiers.length > 0 ? modifiers : undefined}
+      onPress={fire}
+    />
+  );
+}
+
+let warnedShowNoop = false;
+
+/**
+ * A drop-in replacement for `@react-native-menu/menu` on iOS.
+ * Uses SwiftUI `Menu` for tap triggers and `ContextMenu` for long-press triggers.
+ */
+export function MenuView(props: MenuComponentProps & { ref?: React.Ref<MenuComponentRef> }) {
+  const { ref, actions, onPressAction, shouldOpenOnLongPress, title, style, children, testID } =
+    props;
+
+  // SwiftUI `Menu`/`ContextMenu` expose no programmatic open API, so `show()`
+  // can't do anything on iOS. Surface that as a one-time dev warning instead of
+  // silently no-opping.
+  React.useImperativeHandle(
+    ref,
+    () => ({
+      show: () => {
+        if (__DEV__ && !warnedShowNoop) {
+          warnedShowNoop = true;
+          console.warn(
+            '[@expo/ui] MenuView.show() is a no-op on iOS. SwiftUI Menu/ContextMenu have no programmatic open API.'
+          );
+        }
+      },
+    }),
+    []
+  );
+
+  const items = actions.map((action) => renderAction(action, onPressAction));
+  const body = title ? <Section title={title}>{items}</Section> : items;
+
+  // RNHostView requires a single ReactElement; wrap in a fragment so callers
+  // can pass any `ReactNode` (string, array, etc.).
+  const trigger = (
+    <RNHostView matchContents>
+      <>{children}</>
+    </RNHostView>
+  );
+
+  return (
+    <Host matchContents style={style} testID={testID}>
+      {shouldOpenOnLongPress ? (
+        <ContextMenu>
+          <ContextMenu.Trigger>{trigger}</ContextMenu.Trigger>
+          <ContextMenu.Items>{body}</ContextMenu.Items>
+        </ContextMenu>
+      ) : (
+        <Menu label={trigger}>{body}</Menu>
+      )}
+    </Host>
+  );
+}

package/src/community/menu/MenuView.tsx

@@ -0,0 +1,36 @@
+import { type Ref, useEffect, useImperativeHandle } from 'react';
+import { View } from 'react-native';
+
+import type { MenuComponentProps, MenuComponentRef } from './types';
+
+let warned = false;
+
+/**
+ * A drop-in replacement for `@react-native-menu/menu`'s `MenuView`. Wrap any trigger
+ * view; long-pressing or tapping (per `shouldOpenOnLongPress`) shows a popup menu
+ * built from the `actions` tree.
+ *
+ * - On Android, renders via Compose's `DropdownMenu` anchored to a `Pressable`.
+ * - On iOS, renders via SwiftUI's `Menu` (tap) or `ContextMenu` (long-press).
+ * - On web, the trigger renders the trigger but actions do not fire;
+ *   a one-time `console.warn` is emitted.
+ *
+ * @platform android
+ * @platform ios
+ */
+export function MenuView(props: MenuComponentProps & { ref?: Ref<MenuComponentRef> }) {
+  useEffect(() => {
+    if (!warned) {
+      warned = true;
+      console.warn(
+        "[@expo/ui] MenuView is currently Android and iOS-only; the trigger will render but actions won't fire on this platform."
+      );
+    }
+  }, []);
+  useImperativeHandle(props.ref, () => ({ show: () => {} }), []);
+  return (
+    <View style={props.style} testID={props.testID}>
+      {props.children}
+    </View>
+  );
+}

package/src/community/menu/index.tsx

@@ -0,0 +1,14 @@
+import { MenuView } from './MenuView';
+
+export type {
+  MenuAction,
+  MenuAttributes,
+  MenuComponentProps,
+  MenuState,
+  MenuComponentRef,
+  NativeActionEvent,
+} from './types';
+
+export default MenuView;
+// named export needed for docs generator
+export { MenuView };

package/src/community/menu/types.tsx

@@ -0,0 +1,171 @@
+import type { ReactNode } from 'react';
+import type { ColorValue, ImageSourcePropType, StyleProp, ViewStyle } from 'react-native';
+import type { SFSymbol } from 'sf-symbols-typescript';
+
+/**
+ * Visual and behavioral attributes of a menu action.
+ * Compatible with `@react-native-menu/menu`.
+ */
+export type MenuAttributes = {
+  /**
+   * Renders the action with a destructive style (red text/icon).
+   */
+  destructive?: boolean;
+  /**
+   * Disables the action so it can't be activated.
+   */
+  disabled?: boolean;
+  /**
+   * Hides the action from the menu.
+   */
+  hidden?: boolean;
+};
+
+/**
+ * Selection state for a menu action.
+ * `'on'` renders a checkmark; `'off'` doesn't.
+ */
+export type MenuState = 'on' | 'off';
+
+/**
+ * A single action inside a `MenuView`.
+ * Compatible with `@react-native-menu/menu`.
+ */
+export type MenuAction = {
+  /**
+   * Identifier passed back via `onPressAction.nativeEvent.event` when this action is selected.
+   * Defaults to `title` if omitted.
+   */
+  id?: string;
+  /**
+   * Action label shown in the menu.
+   */
+  title: string;
+  /**
+   * Text color of the action label.
+   * @platform android
+   */
+  titleColor?: ColorValue;
+  /**
+   * Icon to render beside the action label.
+   *
+   * - When an `SFSymbol` name (e.g. `'trash'`), rendered on iOS only.
+   *   Not rendered on Android — pass an `ImageSourcePropType` instead to show an
+   *   icon there.
+   * - When an `ImageSourcePropType` (e.g. `require('./trash.xml')` or
+   *   `{ uri: '...' }`), rendered on Android via Compose `Icon`. Ignored on iOS;
+   *   SwiftUI menus only accept SF Symbol names for built-in `Menu`/`Button`
+   *   labels.
+   */
+  image?: SFSymbol | ImageSourcePropType;
+  /**
+   * Tint color applied to the action's icon.
+   *
+   * Visually applied on Android via the leading `Icon`'s tint. On iOS, the
+   * value is accepted but **may not render**: SwiftUI's `Menu`/`ContextMenu`
+   * draw their items via the system menu UI, which ignores per-item color
+   * modifiers.
+   */
+  imageColor?: ColorValue;
+  /**
+   * Selection state. When `'on'`, the action renders a checkmark.
+   */
+  state?: MenuState;
+  /**
+   * Visual/behavioral flags.
+   */
+  attributes?: MenuAttributes;
+  /**
+   * Nested actions. Without `displayInline`, renders as a submenu;
+   * with `displayInline: true`, renders as an inline section.
+   */
+  subactions?: MenuAction[];
+  /**
+   * When `true` and `subactions` is present, renders the children as an inline section
+   * inside the parent menu (with this action's `title` as the section header on iOS).
+   */
+  displayInline?: boolean;
+};
+
+/**
+ * Imperative handle exposed by `MenuView` via `ref`.
+ * Compatible with `@react-native-menu/menu`'s `ref.show()` API.
+ */
+export type MenuComponentRef = {
+  /**
+   * Programmatically open the menu.
+   *
+   * On Android, opens the anchored `DropdownMenu` (equivalent to the user tapping
+   * the trigger). On iOS this is a no-op — SwiftUI `Menu`/`ContextMenu` have no
+   * programmatic open API; a one-time `console.warn` is emitted in development.
+   * @platform android
+   */
+  show: () => void;
+};
+
+/**
+ * Event payload delivered to `onPressAction` when an action is selected.
+ * Compatible with `@react-native-menu/menu`.
+ */
+export type NativeActionEvent = {
+  nativeEvent: {
+    /** Identifier of the pressed action: `action.id ?? action.title`. */
+    event: string;
+  };
+};
+
+/**
+ * Props for the `MenuView` component.
+ * Drop-in compatible with `@react-native-menu/menu`.
+ */
+export type MenuComponentProps = {
+  /**
+   * Menu title shown at the top of the menu.
+   * @platform ios
+   */
+  title?: string;
+  /**
+   * Callback invoked when a menu action is selected.
+   */
+  onPressAction?: (event: NativeActionEvent) => void;
+  /**
+   * Callback invoked when the menu opens.
+   *
+   * On Android, fires when the trigger's tap/long-press flips `expanded` to `true`.
+   * On iOS, SwiftUI `Menu`/`ContextMenu` do not expose an open hook, so this is not
+   * fired there.
+   * @platform android
+   */
+  onOpenMenu?: () => void;
+  /**
+   * Callback invoked when the menu closes (either via dismissal or after an action
+   * fires).
+   *
+   * On Android, fires from the controlled `DropdownMenu`'s dismiss path.
+   * On iOS, SwiftUI `Menu`/`ContextMenu` do not expose a close hook in a way we can
+   * forward, so this is not fired there.
+   * @platform android
+   */
+  onCloseMenu?: () => void;
+  /**
+   * The actions to display in the menu.
+   */
+  actions: MenuAction[];
+  /**
+   * When `true`, the menu opens on long-press of the trigger instead of a single tap.
+   * @default false
+   */
+  shouldOpenOnLongPress?: boolean;
+  /**
+   * Style applied to the trigger wrapper.
+   */
+  style?: StyleProp<ViewStyle>;
+  /**
+   * Test identifier passed through to the trigger view.
+   */
+  testID?: string;
+  /**
+   * Trigger view. Long-pressing or tapping (per `shouldOpenOnLongPress`) opens the menu.
+   */
+  children?: ReactNode;
+};

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

@@ -0,0 +1,92 @@
+import { requireNativeView } from 'expo';
+import { type ColorValue } from 'react-native';
+
+import type { ObservableState } from '../../State/useNativeState';
+import { getStateId } from '../../State/utils';
+import { type ModifierConfig } from '../../types';
+import { createViewModifierEventListener } from '../modifiers/utils';
+
+/**
+ * Common props shared by loading indicator variants.
+ */
+export type LoadingIndicatorCommonConfig = {
+  /**
+   * An observable state that holds the current progress value.
+   * Create one with `useNativeState(0)`. Omit for indeterminate loading.
+   */
+  progress?: ObservableState<number | null>;
+  /**
+   * Loading indicator color.
+   */
+  color?: ColorValue;
+  /**
+   * Modifiers for the component.
+   */
+  modifiers?: ModifierConfig[];
+};
+
+type NativeLoadingIndicatorCommonConfig = Omit<
+  LoadingIndicatorCommonConfig,
+  'progress' | 'modifiers'
+> & {
+  progress?: number;
+  modifiers?: unknown;
+};
+
+function transformProps<T extends LoadingIndicatorCommonConfig>(
+  props: T
+): NativeLoadingIndicatorCommonConfig {
+  const { modifiers, progress, ...restProps } = props;
+  return {
+    modifiers,
+    ...(modifiers ? createViewModifierEventListener(modifiers) : undefined),
+    ...restProps,
+    progress: getStateId(progress),
+  };
+}
+
+function createLoadingIndicatorComponent<P extends LoadingIndicatorCommonConfig>(
+  viewName: string
+): React.ComponentType<P> {
+  const NativeView: React.ComponentType<NativeLoadingIndicatorCommonConfig> = requireNativeView(
+    'ExpoUI',
+    viewName
+  );
+  function Component(props: P) {
+    return <NativeView {...transformProps(props)} />;
+  }
+  Component.displayName = viewName;
+  return Component;
+}
+
+// region LoadingIndicator
+
+/**
+ * A loading indicator that displays loading using morphing shapes.
+ *
+ * Matches the Jetpack Compose `LoadingIndicator`.
+ */
+export const LoadingIndicator = createLoadingIndicatorComponent('LoadingIndicatorView');
+
+// endregion
+
+// region ContainedLoadingIndicator
+
+export type ContainedLoadingIndicatorProps = LoadingIndicatorCommonConfig & {
+  /**
+   * Loading indicator's container color
+   */
+  containerColor?: ColorValue;
+};
+
+/**
+ * A loading indicator that displays loading using morphing shapes inside a container.
+ *
+ * Matches the Jetpack Compose `ContainedLoadingIndicator`.
+ */
+export const ContainedLoadingIndicator =
+  createLoadingIndicatorComponent<ContainedLoadingIndicatorProps>('ContainedLoadingIndicatorView');
+// endregion
+
+// Exported for docs api data
+export { type ObservableState };

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

@@ -0,0 +1,135 @@
+import { requireNativeView } from 'expo';
+import { type Ref } from 'react';
+import { type ColorValue } from 'react-native';
+
+import { type ModifierConfig } from '../../types';
+import { createViewModifierEventListener } from '../modifiers/utils';
+
+export type SnackbarProps = {
+  /**
+   * The background color of the snackbar container.
+   */
+  containerColor?: ColorValue;
+  /**
+   * The preferred content color used for the message text.
+   */
+  contentColor?: ColorValue;
+  /**
+   * The content color used for the action button.
+   */
+  actionContentColor?: ColorValue;
+  /**
+   * The content color used for the dismiss-action icon button.
+   */
+  dismissActionContentColor?: ColorValue;
+  /**
+   * Whether the action should be placed on a new line below the message.
+   * Useful for long action labels.
+   * @default false
+   */
+  actionOnNewLine?: boolean;
+  /**
+   * Modifiers for the component.
+   */
+  modifiers?: ModifierConfig[];
+};
+
+const SnackbarNativeView: React.ComponentType<SnackbarProps> = requireNativeView(
+  'ExpoUI',
+  'SnackbarView'
+);
+
+/**
+ * Styling configuration for the snackbar shown by `SnackbarHost`. Pass as a
+ * child to override colors or place the action on a new line.
+ */
+export function Snackbar(props: SnackbarProps) {
+  const { modifiers, ...rest } = props;
+  return (
+    <SnackbarNativeView
+      modifiers={modifiers}
+      {...(modifiers ? createViewModifierEventListener(modifiers) : undefined)}
+      {...rest}
+    />
+  );
+}
+
+// --- SnackbarHost ---
+
+/**
+ * How long the snackbar is shown. Mirrors Compose's `SnackbarDuration` enum.
+ */
+export type SnackbarDuration = 'short' | 'long' | 'indefinite';
+
+/**
+ * Reason a snackbar invocation resolved. Mirrors Compose's `SnackbarResult` enum.
+ */
+export type SnackbarResult = 'actionPerformed' | 'dismissed';
+
+export type SnackbarShowOptions = {
+  /**
+   * The message body of the snackbar.
+   */
+  message: string;
+  /**
+   * Label for the optional action button. When omitted, no action button is shown.
+   */
+  actionLabel?: string;
+  /**
+   * Whether to show a trailing close (X) icon button to dismiss the snackbar.
+   * @default false
+   */
+  withDismissAction?: boolean;
+  /**
+   * How long to show the snackbar. Defaults to `'short'` when an `actionLabel`
+   * is not provided, and `'indefinite'` when it is, matching Compose.
+   */
+  duration?: SnackbarDuration;
+};
+
+export type SnackbarHostRef = {
+  /**
+   * Shows a snackbar and resolves with `'actionPerformed'` when the user taps
+   * the action, or `'dismissed'` when it times out or the dismiss-action
+   * button is tapped. Subsequent calls queue and show after the current
+   * snackbar is dismissed.
+   */
+  showSnackbar: (options: SnackbarShowOptions) => Promise<SnackbarResult>;
+};
+
+export type SnackbarHostProps = {
+  /**
+   * Ref exposing the imperative `showSnackbar` method.
+   */
+  ref?: Ref<SnackbarHostRef>;
+  /**
+   * Modifiers for the component.
+   */
+  modifiers?: ModifierConfig[];
+  /**
+   * Optional `Snackbar` child supplying styling for shown snackbars. Mirrors
+   * Compose's `SnackbarHost(hostState) { data -> Snackbar(data, ...) }` lambda.
+   */
+  children?: React.ReactNode;
+};
+
+const SnackbarHostNativeView: React.ComponentType<SnackbarHostProps> = requireNativeView(
+  'ExpoUI',
+  'SnackbarHostView'
+);
+
+/**
+ * A Material 3 [SnackbarHost](https://developer.android.com/develop/ui/compose/components/snackbar)
+ * that displays snackbars triggered via its ref's `showSnackbar` method.
+ */
+export function SnackbarHost(props: SnackbarHostProps) {
+  const { modifiers, children, ...rest } = props;
+  return (
+    <SnackbarHostNativeView
+      modifiers={modifiers}
+      {...(modifiers ? createViewModifierEventListener(modifiers) : undefined)}
+      {...rest}>
+      {children}
+    </SnackbarHostNativeView>
+  );
+}

package/src/jetpack-compose/index.ts

@@ -49,6 +49,7 @@ export {
   type HorizontalPagerProps,
 } from './HorizontalPager';
 export * from './SearchBar';
+export * from './Snackbar';
 export * from './DockedSearchBar';
 export * from './HorizontalFloatingToolbar';
 export * from './FloatingActionButton';
@@ -57,6 +58,7 @@ export * from './RadioButton';
 export * from './Surface';
 export { type TextProps, Text } from './Text';
 export * from './Tooltip';
+export * from './LoadingIndicator';
 
 export * from './AnimatedVisibility';
 export * from './Box';

package/src/jetpack-compose/modifiers/index.ts

@@ -1,6 +1,6 @@
 import { type ColorValue } from 'react-native';
 
-import { type AnimatedValue } from './animation';
+import { type AnimatedValue, type AnimationSpec } from './animation';
 import { createModifier, createModifierWithEventListener } from './createModifier';
 export { type ExpoModifier, type ModifierConfig } from '../../types';
 export {
@@ -142,9 +142,12 @@ export const offset = (x: number, y: number) => createModifier('offset', { x, y
 
 /**
  * Sets the background color.
+ * Pass an `animationSpec` to smoothly animate between colors when the prop changes (backed by `animateColorAsState`).
  * @param color - A color string (hex, e.g., `'#FF0000'`).
+ * @param options.animationSpec - Optional spec — animate between color changes.
  */
-export const background = (color: ColorValue) => createModifier('background', { color });
+export const background = (color: ColorValue, options?: { animationSpec?: AnimationSpec }) =>
+  createModifier('background', { color, animationSpec: options?.animationSpec });
 
 /**
  * Adds a border around the view.
@@ -291,6 +294,31 @@ export const clickable = (handler: () => void, options?: { indication?: boolean
     indication: options?.indication ?? true,
   });
 
+/**
+ * Makes the view respond to both click and long-click gestures.
+ * Wraps Compose's `Modifier.combinedClickable`. Useful for triggering a `DropdownMenu`
+ * on long-press while keeping a separate short-press action.
+ * @param handlers.onClick - Function to call on a short tap.
+ * @param handlers.onLongClick - Function to call on a long press.
+ * @param options - Optional configuration.
+ * @param options.indication - Whether to show a ripple indication. Defaults to `true`.
+ */
+export const combinedClickable = (
+  handlers: { onClick?: () => void; onLongClick?: () => void },
+  options?: { indication?: boolean }
+) =>
+  createModifierWithEventListener(
+    'combinedClickable',
+    (params: { event: 'click' | 'longClick' }) => {
+      if (params.event === 'click') {
+        handlers.onClick?.();
+      } else if (params.event === 'longClick') {
+        handlers.onLongClick?.();
+      }
+    },
+    { indication: options?.indication ?? true }
+  );
+
 /**
  * Makes the view selectable, like a radio button row.
  * @param selected - Whether the item is currently selected.