react-native-platform-components 1.5.0 → 1.7.0

package/src/ActionSheetNativeComponent.ts

@@ -0,0 +1,94 @@
+// ActionSheetNativeComponent.ts
+import type { HostComponent, ViewProps } from 'react-native';
+import { codegenNativeComponent } from 'react-native';
+import type { BubblingEventHandler, Double } from './codegenTypes';
+
+/**
+ * One action of the sheet. The list is flat (no submenus or sections) and
+ * hidden actions are already dropped. Every field is set; empty strings mean
+ * "none" and flags are 'true' | 'false'.
+ */
+export type ActionSheetItem = Readonly<{
+  /** Unique identifier returned by onSelect */
+  id: string;
+  title: string;
+  /** '' | 'sfSymbol' | 'drawable' | 'image' (Android draws icons; iOS has no public icon API) */
+  iconType: string;
+  /** SF Symbol / asset name (iOS) or drawable resource name (Android) */
+  iconName: string;
+  /** Resolved image URI when iconType === 'image' */
+  iconRequest: string;
+  iconUri: string;
+  /** Resolved image scale when iconType === 'image' */
+  iconScale: Double;
+  /** 'true' | 'false': draw the image as a tinted template */
+  iconTinted: string;
+  /** Tint color for the icon (hex string, e.g., "#FF0000") */
+  imageColor: string;
+  /** 'true' | 'false' */
+  destructive: string;
+  /** 'true' | 'false' */
+  disabled: string;
+  /** The action's own haptics; '' = the component's */
+  haptics: string;
+  /** accessibilityIdentifier (iOS) / view tag (Android) of the row */
+  testID: string;
+}>;
+
+/**
+ * Event emitted when the user picks an action.
+ */
+export type ActionSheetSelectEvent = Readonly<{
+  /** The action's unique identifier */
+  actionId: string;
+}>;
+
+/** Visibility state (no booleans for codegen). */
+export type ActionSheetVisible = 'open' | 'closed';
+
+export interface ActionSheetProps extends ViewProps {
+  /**
+   * 'open' presents the sheet, 'closed' dismisses it.
+   */
+  visible?: string; // ActionSheetVisible
+
+  /** Sheet title; '' = none */
+  title?: string;
+
+  /** Sheet message under the title; '' = none */
+  message?: string;
+
+  /**
+   * The actions, flat.
+   */
+  actions: ReadonlyArray<ActionSheetItem>;
+
+  /** Title of the iOS cancel action; '' = the localized system "Cancel" */
+  cancelTitle?: string;
+
+  /** accessibilityIdentifier of the iOS cancel action */
+  cancelTestID?: string;
+
+  /**
+   * Haptic played when an action is picked: '' (none added) | 'none' | 'selection' |
+   * 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error'
+   */
+  haptics?: string;
+
+  /** Android: largest font scale the sheet's text may reach; 0 = no cap. */
+  maxFontSizeMultiplier?: Double;
+
+  /**
+   * Fired when the user picks an action.
+   */
+  onSelect?: BubblingEventHandler<ActionSheetSelectEvent>;
+
+  /**
+   * Fired when the sheet is dismissed without a pick.
+   */
+  onCancel?: BubblingEventHandler<Readonly<{}>>;
+}
+
+export default codegenNativeComponent<ActionSheetProps>(
+  'PCActionSheet'
+) as HostComponent<ActionSheetProps>;

package/src/ButtonGroupNativeComponent.ts

@@ -75,6 +75,8 @@ export type ButtonGroupMenuItem = Readonly<{
   state: string;
   /** The action's own haptics; '' = the component's */
   haptics: string;
+  /** Test identifier of the menu row; '' = none */
+  testID: string;
 }>;
 
 /** Event emitted when a split button menu item is picked. */

package/src/ButtonNativeComponent.ts

@@ -59,6 +59,8 @@ export type ButtonMenuItem = Readonly<{
   state: string;
   /** The action's own haptics; '' = the component's */
   haptics: string;
+  /** Test identifier of the menu row; '' = none */
+  testID: string;
 }>;
 
 /** Event emitted when a toggle button is pressed. */

package/src/ContextMenu.tsx

@@ -1,13 +1,17 @@
 // ContextMenu.tsx
-import React, { useCallback, useMemo } from 'react';
-import { type ViewProps } from 'react-native';
+import React, { useCallback, useMemo, useRef } from 'react';
+import { type GestureResponderEvent, type ViewProps } from 'react-native';
 
 import NativeContextMenu, {
+  Commands,
   type ContextMenuPressActionEvent,
 } from './ContextMenuNativeComponent';
 import { flattenMenuActions, type ContextMenuAction } from './menuItems';
 import type { Haptics } from './haptics';
 
+/** How far (in points) a tap may move before it no longer opens the menu. */
+const TAP_SLOP = 10;
+
 export type {
   ContextMenuAction,
   ContextMenuActionAttributes,
@@ -25,10 +29,28 @@ export interface ContextMenuProps extends ViewProps {
 
   /**
    * How the menu is triggered:
-   * - 'longPress' (default): Long-press opens the menu
-   * - 'tap': Single tap opens the menu
+   * - 'longPress' (default): Long-press opens the menu, also on a button
+   *   inside the content; taps still reach the content's buttons
+   * - 'tap': Single tap opens the menu. A tap on a pressable inside the
+   *   content goes to that pressable instead
+   * - 'none': Only `visible` opens the menu. The wrapped content keeps all
+   *   its touches, so it can open the menu from one of its own buttons.
+   */
+  trigger?: 'longPress' | 'tap' | 'none';
+
+  /**
+   * Opens the menu from JS, anchored to the wrapped content. Controlled:
+   * set it to true to open the menu, and back to false in `onMenuClose`,
+   * which fires however the menu closes (an action, a tap outside, or
+   * `visible` turning false). False dismisses an open menu. Leave it unset
+   * to leave the menu to the user; menus the user opens still call
+   * `onMenuOpen` and `onMenuClose`.
+   *
+   * iOS 17.4+ (`UIControl.performPrimaryAction()` on an invisible anchor
+   * button); earlier iOS has no public API to open a menu without a touch,
+   * so `visible` does nothing there.
    */
-  trigger?: 'longPress' | 'tap';
+  visible?: boolean;
 
   /**
    * Haptic played when the user presses an action. Opening the menu keeps
@@ -74,9 +96,8 @@ export interface ContextMenuProps extends ViewProps {
      */
     anchorPosition?: 'left' | 'right';
     /**
-     * Programmatic visibility control (Android only).
-     * Set to true to open the menu, false to close it.
-     * Note: iOS does not support programmatic menu opening.
+     * @deprecated Use the top-level `visible`, which also works on iOS.
+     * When both are set, the top-level one wins.
      */
     visible?: boolean;
   };
@@ -92,6 +113,7 @@ export function ContextMenu(props: ContextMenuProps): React.ReactElement {
     actions,
     disabled,
     trigger = 'longPress',
+    visible,
     haptics,
     onPressAction,
     onMenuOpen,
@@ -105,6 +127,40 @@ export function ContextMenu(props: ContextMenuProps): React.ReactElement {
 
   const nativeActions = useMemo(() => flattenMenuActions(actions), [actions]);
 
+  const nativeRef = useRef<React.ComponentRef<typeof NativeContextMenu>>(null);
+  // Where the current tap went down; null once it moved too far
+  const tapStart = useRef<{ x: number; y: number } | null>(null);
+
+  // trigger 'tap': React Native gives a touch to the deepest view that asks
+  // for it, so the content's own pressables keep their taps. A tap none of
+  // them took bubbles up to this view, and opens the menu.
+  const tapHandlers = useMemo(() => {
+    if (trigger !== 'tap' || disabled) return undefined;
+    return {
+      onStartShouldSetResponder: () => true,
+      onResponderGrant: (e: GestureResponderEvent) => {
+        tapStart.current = { x: e.nativeEvent.pageX, y: e.nativeEvent.pageY };
+      },
+      onResponderMove: (e: GestureResponderEvent) => {
+        const start = tapStart.current;
+        if (!start) return;
+        const { pageX, pageY } = e.nativeEvent;
+        if (Math.hypot(pageX - start.x, pageY - start.y) > TAP_SLOP) {
+          tapStart.current = null;
+        }
+      },
+      onResponderRelease: () => {
+        const node = nativeRef.current;
+        if (tapStart.current && node != null) Commands.handleTap(node);
+        tapStart.current = null;
+      },
+      // A scroll view took the touch over
+      onResponderTerminate: () => {
+        tapStart.current = null;
+      },
+    };
+  }, [trigger, disabled]);
+
   const handlePressAction = useCallback(
     (e: { nativeEvent: ContextMenuPressActionEvent }) => {
       const { actionId, actionTitle } = e.nativeEvent;
@@ -134,19 +190,22 @@ export function ContextMenu(props: ContextMenuProps): React.ReactElement {
 
   const nativeAndroid = useMemo(() => {
     if (!android) return undefined;
-    return {
-      anchorPosition: android.anchorPosition,
-      visible: android.visible ? 'open' : 'closed',
-    };
+    return { anchorPosition: android.anchorPosition };
   }, [android]);
 
+  // The deprecated android.visible still works, under the top-level prop
+  const open = visible ?? android?.visible;
+
   return (
     <NativeContextMenu
+      ref={nativeRef}
+      {...tapHandlers}
       style={style}
       title={title}
       actions={nativeActions}
       interactivity={disabled ? 'disabled' : 'enabled'}
       trigger={trigger}
+      visible={open === undefined ? undefined : open ? 'open' : 'closed'}
       haptics={haptics ?? ''}
       onPressAction={onPressAction ? handlePressAction : undefined}
       onMenuOpen={onMenuOpen ? handleMenuOpen : undefined}

package/src/ContextMenuNativeComponent.ts

@@ -1,6 +1,7 @@
 // ContextMenuNativeComponent.ts
+import type * as React from 'react';
 import type { HostComponent, ViewProps } from 'react-native';
-import { codegenNativeComponent } from 'react-native';
+import { codegenNativeCommands, codegenNativeComponent } from 'react-native';
 import type { BubblingEventHandler, Double, Int32 } from './codegenTypes';
 
 /**
@@ -43,6 +44,8 @@ export type ContextMenuItem = Readonly<{
   state: string;
   /** The action's own haptics; '' = the component's */
   haptics: string;
+  /** Test identifier of the menu row; '' = none */
+  testID: string;
 }>;
 
 /**
@@ -59,7 +62,7 @@ export type ContextMenuPressActionEvent = Readonly<{
 export type ContextMenuInteractivity = 'enabled' | 'disabled';
 
 /** Trigger mode for opening the menu. */
-export type ContextMenuTrigger = 'longPress' | 'tap';
+export type ContextMenuTrigger = 'longPress' | 'tap' | 'none';
 
 /**
  * iOS-specific configuration.
@@ -75,11 +78,6 @@ export type IOSProps = Readonly<{
 export type AndroidProps = Readonly<{
   /** Anchor position for the popup menu */
   anchorPosition?: string; // 'left' | 'right'
-  /**
-   * Programmatic visibility control (Android only).
-   * 'open' to show the menu, 'closed' to hide it.
-   */
-  visible?: string; // 'open' | 'closed'
 }>;
 
 export interface ContextMenuProps extends ViewProps {
@@ -102,9 +100,16 @@ export interface ContextMenuProps extends ViewProps {
    * How the menu is triggered:
    * - 'longPress' (default): Long-press opens the menu
    * - 'tap': Single tap opens the menu
+   * - 'none': only `visible` opens it; the content keeps its touches
    */
   trigger?: string; // ContextMenuTrigger
 
+  /**
+   * Programmatic visibility: 'open' presents the menu anchored to the view,
+   * 'closed' dismisses it. '' (unset) leaves the menu to the user.
+   */
+  visible?: string; // '' | 'open' | 'closed'
+
   /**
    * Haptic played when an action is pressed: '' (none added) | 'none' | 'selection' |
    * 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error'
@@ -135,6 +140,22 @@ export interface ContextMenuProps extends ViewProps {
   android?: AndroidProps;
 }
 
+type NativeContextMenuComponent = HostComponent<ContextMenuProps>;
+
+// `React.ElementRef` rather than `React.ComponentRef`: the codegen shipped with
+// React Native 0.81 (and the 0.76 Android floor) only accepts the former.
+interface NativeCommands {
+  /**
+   * trigger 'tap': the user tapped the content and no inner pressable took
+   * the tap. Opens the menu (iOS 17.4+; earlier iOS opens it natively).
+   */
+  handleTap: (viewRef: React.ElementRef<NativeContextMenuComponent>) => void;
+}
+
+export const Commands: NativeCommands = codegenNativeCommands<NativeCommands>({
+  supportedCommands: ['handleTap'],
+});
+
 export default codegenNativeComponent<ContextMenuProps>(
   'PCContextMenu'
-) as HostComponent<ContextMenuProps>;
+) as NativeContextMenuComponent;

package/src/index.tsx

@@ -1,6 +1,7 @@
 export * from './DatePicker';
 export * from './SelectionMenu';
 export * from './ContextMenu';
+export * from './ActionSheet';
 export * from './SegmentedControl';
 export * from './TabBar';
 export * from './FloatingActionButton';

package/src/index.web.tsx

@@ -8,6 +8,7 @@
 export type * from './DatePicker';
 export type * from './SelectionMenu';
 export type * from './ContextMenu';
+export type * from './ActionSheet';
 export type * from './SegmentedControl';
 export type * from './TabBar';
 export type * from './FloatingActionButton';
@@ -33,6 +34,7 @@ export type {
 } from './webComponents';
 export { PlatformComponentsProvider } from './web/PlatformComponentsProvider';
 export {
+  ActionSheet,
   Button,
   ButtonGroup,
   SplitButton,

package/src/jest.tsx

@@ -27,9 +27,10 @@ import {
   type ViewProps,
 } from 'react-native';
 
+import type { ActionSheetProps } from './ActionSheet';
 import type { ButtonProps } from './Button';
 import type { ButtonGroupProps } from './ButtonGroup';
-import type { ContextMenuProps } from './ContextMenu';
+import type { ContextMenuAction, ContextMenuProps } from './ContextMenu';
 import type { DatePickerProps, DateRangePickerProps } from './DatePicker';
 import type { FloatingActionButtonProps } from './FloatingActionButton';
 import type { FloatingToolbarProps } from './FloatingToolbar';
@@ -54,6 +55,7 @@ import { nextSelection } from './web/ButtonGroup';
 export type * from './DatePicker';
 export type * from './SelectionMenu';
 export type * from './ContextMenu';
+export type * from './ActionSheet';
 export type * from './Button';
 export type * from './ButtonGroup';
 export type * from './SplitButton';
@@ -845,9 +847,12 @@ export function SelectionMenu(props: SelectionMenuProps): React.ReactElement {
 }
 
 /**
- * Its children in a view carrying `testID`. The menu itself isn't rendered;
- * `fireEvent(menu, 'pressAction', id, title)`, `'menuOpen'`, `'menuClose'`
- * and `'previewPress'` reach the callbacks.
+ * Its children in a view carrying `testID`. While `visible` (or the
+ * deprecated `android.visible`) is true, each action follows them as a
+ * `Pressable` with the `menuitem` role and the action's `testID` (else
+ * `${testID}-${id}`) that calls `onPressAction(id, title)`; submenus and
+ * sections list their actions. `fireEvent(menu, 'pressAction', id, title)`,
+ * `'menuOpen'`, `'menuClose'` and `'previewPress'` reach the callbacks.
  */
 export function ContextMenu(props: ContextMenuProps): React.ReactElement {
   const {
@@ -860,18 +865,117 @@ export function ContextMenu(props: ContextMenuProps): React.ReactElement {
     actions,
     disabled,
     trigger,
+    visible,
     haptics,
     ios,
     android,
+    testID,
     ...viewProps
   } = props;
 
+  const open = !disabled && !!(visible ?? android?.visible);
+  const leaves = (list: ContextMenuProps['actions']): ContextMenuAction[] =>
+    list.flatMap((action) =>
+      action.attributes?.hidden
+        ? []
+        : action.subactions?.length
+          ? leaves(action.subactions)
+          : [action]
+    );
+
   return (
     <View
       {...viewProps}
+      testID={testID}
       {...handlers({ onPressAction, onMenuOpen, onMenuClose, onPreviewPress })}
     >
       {children}
+      {open
+        ? leaves(actions).map((action) => (
+            <Pressable
+              key={action.id}
+              testID={
+                action.testID ?? (testID ? `${testID}-${action.id}` : undefined)
+              }
+              accessibilityRole="menuitem"
+              accessibilityState={{ disabled: !!action.attributes?.disabled }}
+              disabled={action.attributes?.disabled}
+              onPress={() => onPressAction?.(action.id, action.title)}
+            >
+              <Text>{action.title}</Text>
+            </Pressable>
+          ))
+        : null}
+    </View>
+  );
+}
+
+/**
+ * Its children in a view carrying `testID`. While `visible`, the title and
+ * message show as `Text`, and each shown action is a `Pressable` with its
+ * `testID` (else `${testID}-${id}`) that calls `onSelect(id)`; a disabled
+ * one ignores presses. A cancel `Pressable` with `cancelTestID` (else
+ * `${testID}-cancel`) calls `onCancel`. `fireEvent(sheet, 'select', id)` and
+ * `fireEvent(sheet, 'cancel')` also work.
+ */
+export function ActionSheet(props: ActionSheetProps): React.ReactElement {
+  const {
+    visible,
+    title,
+    message,
+    actions,
+    cancelTitle,
+    cancelTestID,
+    haptics,
+    maxFontSizeMultiplier,
+    onSelect,
+    onCancel,
+    testID,
+    children,
+    ...viewProps
+  } = props;
+
+  return (
+    <View
+      {...viewProps}
+      testID={testID}
+      accessibilityState={{ expanded: visible }}
+      {...handlers({ onSelect, onCancel })}
+    >
+      {children}
+      {visible ? (
+        <View accessibilityRole="menu">
+          {title ? <Text>{title}</Text> : null}
+          {message ? <Text>{message}</Text> : null}
+          {actions
+            .filter((action) => !action.attributes?.hidden)
+            .map((action) => {
+              const disabled = !!action.attributes?.disabled;
+              return (
+                <Pressable
+                  key={action.id}
+                  testID={
+                    action.testID ??
+                    (testID ? `${testID}-${action.id}` : undefined)
+                  }
+                  accessibilityRole="menuitem"
+                  accessibilityState={{ disabled }}
+                  disabled={disabled}
+                  onPress={() => onSelect?.(action.id)}
+                >
+                  <Text>{action.title}</Text>
+                </Pressable>
+              );
+            })}
+          <Pressable
+            testID={cancelTestID ?? (testID ? `${testID}-cancel` : undefined)}
+            accessibilityRole="button"
+            onPress={() => onCancel?.()}
+          >
+            <Text>{cancelTitle ?? 'Cancel'}</Text>
+          </Pressable>
+        </View>
+      ) : null}
     </View>
   );
 }

package/src/menuItems.ts

@@ -69,6 +69,16 @@ export interface ContextMenuAction {
    * - Android: a menu group with group dividers; the title is not shown.
    */
   displayInline?: boolean;
+  /**
+   * Test identifier of the action's menu row, so UI tests (Detox `by.id`)
+   * find it without its title. A submenu's row takes one too; an inline
+   * section has no row of its own.
+   *
+   * - iOS: the `accessibilityIdentifier` of the `UIAction` / `UIMenu`.
+   * - Android 10+: the tag of the popup row view, which Detox and Espresso
+   *   match `by.id` against. Not a resource-id.
+   */
+  testID?: string;
 }
 
 /**
@@ -99,6 +109,8 @@ export type NativeMenuItem = {
   state: string;
   /** The action's own haptics; '' = the component's */
   haptics: string;
+  /** Test identifier of the menu row; '' = none */
+  testID: string;
 };
 
 const flag = (value: boolean | undefined) => (value ? 'true' : 'false');
@@ -141,6 +153,7 @@ export function flattenMenuActions(
         keepsMenuPresented: flag(attributes?.keepsMenuPresented),
         state: action.state ?? '',
         haptics: action.haptics ?? '',
+        testID: action.testID ?? '',
       });
 
       if (kind !== 'action') visit(children, index);

package/src/selectionIdentifiers.ts

@@ -1,6 +1,6 @@
 /** Diagnose identifiers reserved by the native selection protocol. */
 export function warnSelectionIdentifiers(
-  component: 'SelectionMenu' | 'SegmentedControl',
+  component: 'SelectionMenu' | 'SegmentedControl' | 'ActionSheet',
   values: readonly string[]
 ): void {
   if (!__DEV__) return;

package/src/web/ActionSheet.tsx

@@ -0,0 +1,130 @@
+// web/ActionSheet.tsx
+import React from 'react';
+import { View } from 'react-native';
+
+import type { ActionSheetProps } from '../ActionSheet';
+import { Dialog } from './Dialog';
+import { Icon } from './Icon';
+
+// Material 3 baseline error color, as on Android
+const DESTRUCTIVE_COLOR = '#B3261E';
+
+/**
+ * Renders its children; while `visible`, the title, message and actions open
+ * in a `<dialog>` with a cancel button below them. Picking an action calls
+ * `onSelect`; the cancel button, Escape and a click outside call `onCancel`.
+ * Icons draw only for image sources (`{ type: 'image' }`); each button
+ * carries its action's `testID` as `data-testid`.
+ */
+export function ActionSheet(props: ActionSheetProps): React.ReactElement {
+  const {
+    visible,
+    title,
+    message,
+    actions,
+    cancelTitle,
+    cancelTestID,
+    haptics,
+    maxFontSizeMultiplier,
+    onSelect,
+    onCancel,
+    accessibilityLabel,
+    children,
+    ...viewProps
+  } = props;
+
+  const label = accessibilityLabel ?? title ?? 'Actions';
+  const shown = actions.filter((action) => !action.attributes?.hidden);
+  const cancel = () => onCancel?.();
+
+  return (
+    <View {...viewProps}>
+      {children}
+      {visible ? (
+        <Dialog label={label} onDismiss={cancel}>
+          <div
+            style={{ display: 'flex', flexDirection: 'column', minWidth: 240 }}
+          >
+            {title || message ? (
+              <div style={{ padding: '4px 12px 12px', textAlign: 'center' }}>
+                {title ? (
+                  <div style={{ fontSize: 15, fontWeight: 600 }}>{title}</div>
+                ) : null}
+                {message ? (
+                  <div style={{ fontSize: 13, opacity: 0.7, marginTop: 4 }}>
+                    {message}
+                  </div>
+                ) : null}
+              </div>
+            ) : null}
+            {shown.map((action, index) => {
+              const destructive = !!action.attributes?.destructive;
+              const color = destructive ? DESTRUCTIVE_COLOR : 'inherit';
+              return (
+                <button
+                  key={action.id}
+                  type="button"
+                  data-testid={action.testID}
+                  disabled={action.attributes?.disabled}
+                  autoFocus={
+                    index ===
+                    shown.findIndex((item) => !item.attributes?.disabled)
+                  }
+                  onClick={() => {
+                    if (!action.attributes?.disabled) onSelect?.(action.id);
+                  }}
+                  style={{
+                    display: 'flex',
+                    alignItems: 'center',
+                    gap: 12,
+                    minHeight: 44,
+                    padding: '0 12px',
+                    border: 'none',
+                    borderRadius: 8,
+                    fontFamily: 'inherit',
+                    fontSize: 16,
+                    textAlign: 'start',
+                    color,
+                    opacity: action.attributes?.disabled ? 0.4 : 1,
+                    backgroundColor: 'transparent',
+                    cursor: action.attributes?.disabled ? 'default' : 'pointer',
+                  }}
+                >
+                  <Icon
+                    icon={action.image}
+                    color={
+                      action.imageColor ??
+                      (destructive ? DESTRUCTIVE_COLOR : 'CanvasText')
+                    }
+                  />
+                  <span>{action.title}</span>
+                </button>
+              );
+            })}
+            <button
+              type="button"
+              data-testid={cancelTestID}
+              onClick={cancel}
+              style={{
+                minHeight: 44,
+                marginTop: 8,
+                padding: '0 12px',
+                border: 'none',
+                borderRadius: 8,
+                fontFamily: 'inherit',
+                fontSize: 16,
+                fontWeight: 600,
+                color: 'inherit',
+                backgroundColor:
+                  'color-mix(in srgb, CanvasText 8%, transparent)',
+                cursor: 'pointer',
+              }}
+            >
+              {cancelTitle ?? 'Cancel'}
+            </button>
+          </div>
+        </Dialog>
+      ) : null}
+    </View>
+  );
+}