react-native-platform-components 1.3.0 → 1.5.0

package/src/ButtonGroupNativeComponent.ts

@@ -0,0 +1,191 @@
+// ButtonGroupNativeComponent.ts
+import type { ColorValue, HostComponent, ViewProps } from 'react-native';
+import { codegenNativeComponent } from 'react-native';
+import type { BubblingEventHandler, Double, Int32 } from './codegenTypes';
+
+/**
+ * A single button in the group. Icons are pre-resolved on the JS side (see
+ * icons.ts) so native only deals with flat strings.
+ */
+export type ButtonGroupButton = Readonly<{
+  label: string; // Empty for an icon-only button
+  value: string;
+  disabled: string; // 'enabled' | 'disabled'
+  iconType: string; // '' | 'sfSymbol' | 'drawable' | 'image'
+  iconName: string; // SF Symbol (iOS) or drawable resource name (Android)
+  iconRequest: string;
+  iconUri: string; // Resolved image URI when iconType === 'image'
+  iconScale: Double; // Resolved image scale when iconType === 'image'
+  iconTinted: string; // 'true' | 'false' — draw the image as a tinted template
+  accessibilityLabel: string; // Screen-reader label, empty = use label
+}>;
+
+/**
+ * Event emitted when a button is pressed.
+ */
+export type ButtonGroupPressEvent = Readonly<{
+  index: Int32;
+  value: string;
+}>;
+
+/**
+ * Event emitted when the selection changes (single / multiple selection).
+ */
+export type ButtonGroupSelectionEvent = Readonly<{
+  /** Values of the selected buttons, in button order. */
+  // Codegen only understands the `T[]` array form in event payloads.
+  values: string[];
+}>;
+
+/**
+ * Label font. Empty strings / 0 mean "platform default".
+ */
+export type ButtonGroupLabelStyleProps = Readonly<{
+  fontFamily?: string;
+  fontSize?: Double;
+  fontWeight?: string; // 'normal' | 'bold' | '100'..'900'
+  fontStyle?: string; // 'normal' | 'italic'
+}>;
+
+/**
+ * One item of the split button's menu, the shape of `ContextMenuItem` (see
+ * menuItems.ts). Every field is set; empty strings mean "none" and flags are
+ * 'true' | 'false'.
+ */
+export type ButtonGroupMenuItem = Readonly<{
+  id: string;
+  title: string;
+  subtitle: string;
+  /** Index of the parent submenu or section; -1 at the top level */
+  parent: Int32;
+  /** 'action' | 'menu' | 'section' */
+  kind: string;
+  /** '' | 'sfSymbol' | 'drawable' | 'image' */
+  iconType: string;
+  iconName: string;
+  iconRequest: string;
+  iconUri: string;
+  iconScale: Double;
+  iconTinted: string;
+  imageColor: string;
+  destructive: string;
+  disabled: string;
+  keepsMenuPresented: string;
+  /** '' | 'off' | 'on' | 'mixed' */
+  state: string;
+  /** The action's own haptics; '' = the component's */
+  haptics: string;
+}>;
+
+/** Event emitted when a split button menu item is picked. */
+export type ButtonGroupMenuSelectEvent = Readonly<{
+  id: string;
+  title: string;
+}>;
+
+/**
+ * Android-specific configuration.
+ */
+export type ButtonGroupAndroidProps = Readonly<{
+  /** Material style: 'm3' | 'expressive' */
+  material?: string;
+}>;
+
+export interface ButtonGroupNativeProps extends ViewProps {
+  /** Buttons to display. */
+  buttons: ReadonlyArray<ButtonGroupButton>;
+
+  /**
+   * 'filled' | 'tonal' | 'outlined' | 'text' | 'elevated' | 'glass' |
+   * 'prominentGlass' | 'clearGlass' | 'prominentClearGlass'
+   */
+  variant?: string;
+
+  /** 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' */
+  size?: string;
+
+  /** '' (platform default) | 'round' | 'square' */
+  shape?: string;
+
+  /** 'true' | 'false': connected group (shared outline, small inner corners) */
+  connected?: string;
+
+  /** Gap between buttons in points; negative means the platform default. */
+  spacing?: Double;
+
+  /** 'none' | 'single' | 'multiple' */
+  selection?: string;
+
+  /** Values of the selected buttons (single / multiple selection). */
+  selectedValues?: ReadonlyArray<string>;
+
+  /** 'true' | 'false': whether at least one button must stay selected */
+  selectionRequired?: string;
+
+  /** 'enabled' | 'disabled' */
+  interactivity?: string;
+
+  /** Container (background) color of the buttons. */
+  color?: ColorValue;
+
+  /** Label and icon color of the buttons. */
+  foregroundColor?: ColorValue;
+
+  /** Android: ripple color shown while pressing a button. */
+  androidRippleColor?: ColorValue;
+
+  /** Android: outline color (outlined variant). */
+  androidStrokeColor?: ColorValue;
+
+  /** Label font. */
+  labelStyle?: ButtonGroupLabelStyleProps;
+
+  /**
+   * What happens to buttons that don't fit: 'none' | 'menu' | 'wrap'
+   * ('wrap' is Android only)
+   */
+  overflow?: string;
+
+  /**
+   * 'true' | 'false': a split button, the first button joined to a trailing
+   * button that opens `menu` (SplitButton).
+   */
+  split?: string;
+
+  /** The split button's menu, flattened (see ButtonGroupMenuItem). */
+  menu?: ReadonlyArray<ButtonGroupMenuItem>;
+
+  /** Screen-reader label of the split button's menu button. */
+  menuAccessibilityLabel?: string;
+
+  /**
+   * Haptic played when a button is pressed: '' (none added) | 'none' | 'selection' |
+   * 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error'
+   */
+  haptics?: string;
+
+  /** Fired when a button is pressed. */
+  onButtonPress?: BubblingEventHandler<ButtonGroupPressEvent>;
+
+  /**
+   * Fired when the selection changes. Not `onSelectionChange`: React Native's
+   * TextInput registers `topSelectionChange` as a direct event, and an event
+   * name can't be both direct and bubbling.
+   */
+  onGroupSelectionChange?: BubblingEventHandler<ButtonGroupSelectionEvent>;
+
+  /** Fired when a split button menu item is picked. */
+  onMenuSelect?: BubblingEventHandler<ButtonGroupMenuSelectEvent>;
+
+  /** Fired when the split button's menu opens. */
+  onMenuOpen?: BubblingEventHandler<Readonly<{}>>;
+
+  /** Fired when the split button's menu closes. */
+  onMenuClose?: BubblingEventHandler<Readonly<{}>>;
+
+  android?: ButtonGroupAndroidProps;
+}
+
+export default codegenNativeComponent<ButtonGroupNativeProps>(
+  'PCButtonGroup'
+) as HostComponent<ButtonGroupNativeProps>;

package/src/ButtonNativeComponent.ts

@@ -0,0 +1,192 @@
+// ButtonNativeComponent.ts
+import type { ColorValue, HostComponent, ViewProps } from 'react-native';
+import { codegenNativeComponent } from 'react-native';
+import type {
+  BubblingEventHandler,
+  Double,
+  Int32,
+  WithDefault,
+} from './codegenTypes';
+
+/**
+ * Icon fields, pre-resolved on the JS side (see icons.ts).
+ */
+export type ButtonIconProps = Readonly<{
+  iconType: string; // '' | 'sfSymbol' | 'drawable' | 'image'
+  iconName: string; // SF Symbol (iOS) or drawable resource name (Android)
+  iconRequest: string;
+  iconUri: string; // Resolved image URI when iconType === 'image'
+  iconScale: Double; // Resolved image scale when iconType === 'image'
+  iconTinted: string; // 'true' | 'false' — draw the image as a tinted template
+}>;
+
+/**
+ * Label font. Empty strings / 0 mean "platform default".
+ */
+export type ButtonLabelStyleProps = Readonly<{
+  fontFamily?: string;
+  fontSize?: Double;
+  fontWeight?: string; // 'normal' | 'bold' | '100'..'900'
+  fontStyle?: string; // 'normal' | 'italic'
+}>;
+
+/**
+ * One menu item, the shape of `ContextMenuItem`: the JS action tree is
+ * flattened (see `menuItems.ts`) and each item points at its parent submenu
+ * or section by index. Every field is set; empty strings mean "none" and
+ * flags are 'true' | 'false'.
+ */
+export type ButtonMenuItem = Readonly<{
+  id: string;
+  title: string;
+  subtitle: string;
+  /** Index of the parent submenu or section; -1 at the top level */
+  parent: Int32;
+  /** 'action' | 'menu' | 'section' */
+  kind: string;
+  /** '' | 'sfSymbol' | 'drawable' | 'image' */
+  iconType: string;
+  iconName: string;
+  iconRequest: string;
+  iconUri: string;
+  iconScale: Double;
+  iconTinted: string;
+  imageColor: string;
+  destructive: string;
+  disabled: string;
+  keepsMenuPresented: string;
+  /** '' | 'off' | 'on' | 'mixed' */
+  state: string;
+  /** The action's own haptics; '' = the component's */
+  haptics: string;
+}>;
+
+/** Event emitted when a toggle button is pressed. */
+export type ButtonSelectedChangeEvent = Readonly<{
+  /** The selection the press asks for */
+  selected: boolean;
+}>;
+
+/** Event emitted when a menu item is picked. */
+export type ButtonMenuSelectEvent = Readonly<{
+  id: string;
+  title: string;
+}>;
+
+/**
+ * iOS-specific configuration.
+ */
+export type ButtonIOSProps = Readonly<{
+  /** '' | 'bounce' | 'pulse' | 'variableColor' | 'wiggle' | 'rotate' | 'breathe' */
+  symbolEffect?: string;
+
+  /**
+   * '' runs the effect indefinitely; otherwise it plays once each time this
+   * value changes.
+   */
+  symbolEffectTrigger?: string;
+}>;
+
+export interface ButtonNativeProps extends ViewProps {
+  /** Button text. Empty for an icon-only button. */
+  label?: string;
+
+  /** Icon shown next to the label, or alone when there is no label. */
+  icon?: ButtonIconProps;
+
+  /** 'leading' | 'trailing' | 'top' | 'bottom' */
+  iconPosition?: string;
+
+  /**
+   * 'filled' | 'tonal' | 'outlined' | 'text' | 'elevated' | 'glass' |
+   * 'prominentGlass' | 'clearGlass' | 'prominentClearGlass'
+   */
+  variant?: string;
+
+  /** 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' */
+  size?: string;
+
+  /** '' (platform default) | 'round' | 'square' */
+  shape?: string;
+
+  /** Corner radius in points; negative = use `shape`. */
+  cornerRadius?: WithDefault<Double, -1>;
+
+  /** 'enabled' | 'disabled' */
+  interactivity?: string;
+
+  /** 'true' | 'false': spinner in place of the label and icon, presses ignored. */
+  loading?: string;
+
+  /** Container (background) color. */
+  color?: ColorValue;
+
+  /** Label and icon color. */
+  foregroundColor?: ColorValue;
+
+  /** Container color while disabled; unset = platform disabled look. */
+  disabledColor?: ColorValue;
+
+  /** Label and icon color while disabled; unset = platform disabled look. */
+  disabledForegroundColor?: ColorValue;
+
+  /** Android: ripple color shown while pressing. */
+  androidRippleColor?: ColorValue;
+
+  /** Android: outline color (outlined variant). */
+  androidStrokeColor?: ColorValue;
+
+  /** Android: Material style, 'm3' | 'expressive' */
+  androidMaterial?: string;
+
+  /** Label font. */
+  labelStyle?: ButtonLabelStyleProps;
+
+  /** Cap on the label's font scaling; 0 (or below 1) = no cap. */
+  maxFontSizeMultiplier?: Double;
+
+  /**
+   * Screen-reader label, applied to the native button rather than the host
+   * view. Empty means "use the label".
+   */
+  spokenLabel?: string;
+
+  /** '' (not a toggle) | 'true' | 'false': the controlled toggle state. */
+  selected?: string;
+
+  /**
+   * Bumped by JS after every onSelectedChange, so native applies `selected`
+   * again: a toggle the parent didn't accept goes back.
+   */
+  selectedEventCount?: Int32;
+
+  /** Menu shown when the button is pressed, flattened (see ButtonMenuItem). */
+  menu?: ReadonlyArray<ButtonMenuItem>;
+
+  ios?: ButtonIOSProps;
+
+  /**
+   * Haptic played when the button is pressed: '' (none added) | 'none' | 'selection' |
+   * 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error'
+   */
+  haptics?: string;
+
+  /** Fired when the button is pressed. */
+  onButtonPress?: BubblingEventHandler<Readonly<{}>>;
+
+  /** Fired when a toggle button is pressed, with the state it asks for. */
+  onSelectedChange?: BubblingEventHandler<ButtonSelectedChangeEvent>;
+
+  /** Fired when a menu item is picked. */
+  onMenuSelect?: BubblingEventHandler<ButtonMenuSelectEvent>;
+
+  /** Fired when the menu opens. */
+  onMenuOpen?: BubblingEventHandler<Readonly<{}>>;
+
+  /** Fired when the menu closes. */
+  onMenuClose?: BubblingEventHandler<Readonly<{}>>;
+}
+
+export default codegenNativeComponent<ButtonNativeProps>(
+  'PCButton'
+) as HostComponent<ButtonNativeProps>;

package/src/ContextMenu.tsx

@@ -3,44 +3,15 @@ import React, { useCallback, useMemo } from 'react';
 import { type ViewProps } from 'react-native';
 
 import NativeContextMenu, {
-  type ContextMenuAction as NativeAction,
-  type ContextMenuSubaction as NativeSubaction,
   type ContextMenuPressActionEvent,
 } from './ContextMenuNativeComponent';
+import { flattenMenuActions, type ContextMenuAction } from './menuItems';
+import type { Haptics } from './haptics';
 
-/**
- * Attributes for a context menu action.
- */
-export interface ContextMenuActionAttributes {
-  /** Whether the action is destructive (red styling) */
-  destructive?: boolean;
-  /** Whether the action is disabled (grayed out) */
-  disabled?: boolean;
-  /** Whether the action is hidden */
-  hidden?: boolean;
-}
-
-/**
- * A single action in the context menu.
- */
-export interface ContextMenuAction {
-  /** Unique identifier returned in callbacks */
-  id: string;
-  /** Display title */
-  title: string;
-  /** Secondary text (iOS only) */
-  subtitle?: string;
-  /** Icon name (SF Symbol on iOS, drawable resource on Android) */
-  image?: string;
-  /** Tint color for the icon (hex string or named color) */
-  imageColor?: string;
-  /** Action attributes */
-  attributes?: ContextMenuActionAttributes;
-  /** Checkmark state */
-  state?: 'off' | 'on' | 'mixed';
-  /** Nested actions for submenu */
-  subactions?: readonly ContextMenuAction[];
-}
+export type {
+  ContextMenuAction,
+  ContextMenuActionAttributes,
+} from './menuItems';
 
 export interface ContextMenuProps extends ViewProps {
   /** Menu title (shown as header on iOS) */
@@ -59,6 +30,13 @@ export interface ContextMenuProps extends ViewProps {
    */
   trigger?: 'longPress' | 'tap';
 
+  /**
+   * Haptic played when the user presses an action. Opening the menu keeps
+   * the platform's own long-press haptic; `'none'` also turns that off on
+   * Android (iOS offers no switch for it). See {@link Haptics}.
+   */
+  haptics?: Haptics;
+
   /**
    * Called when the user presses an action.
    * Receives the action's id and title.
@@ -71,6 +49,14 @@ export interface ContextMenuProps extends ViewProps {
   /** Called when the menu closes */
   onMenuClose?: () => void;
 
+  /**
+   * iOS only: called when the user taps the menu's preview (with
+   * `ios.enablePreview`), after the menu has dismissed. Use it to open the
+   * item, like tapping a preview in Photos or Mail. Maps to
+   * `contextMenuInteraction(_:willPerformPreviewActionForMenuWith:animator:)`.
+   */
+  onPreviewPress?: () => void;
+
   /** The content to wrap */
   children: React.ReactNode;
 
@@ -82,7 +68,10 @@ export interface ContextMenuProps extends ViewProps {
 
   /** Android-specific props */
   android?: {
-    /** Anchor position for the popup menu */
+    /**
+     * Aligns the popup with the start ('left', default) or end ('right') edge
+     * of the wrapped content. Mirrored in RTL layouts.
+     */
     anchorPosition?: 'left' | 'right';
     /**
      * Programmatic visibility control (Android only).
@@ -96,50 +85,6 @@ export interface ContextMenuProps extends ViewProps {
   testID?: string;
 }
 
-/**
- * Convert user-friendly subaction to native format (no further nesting).
- */
-function normalizeSubaction(action: ContextMenuAction): NativeSubaction {
-  return {
-    id: action.id,
-    title: action.title,
-    subtitle: action.subtitle,
-    image: action.image,
-    imageColor: action.imageColor,
-    attributes: action.attributes
-      ? {
-          destructive: action.attributes.destructive ? 'true' : 'false',
-          disabled: action.attributes.disabled ? 'true' : 'false',
-          hidden: action.attributes.hidden ? 'true' : 'false',
-        }
-      : undefined,
-    state: action.state,
-  };
-}
-
-/**
- * Convert user-friendly action to native format.
- * Note: Only one level of nesting is supported by the native component.
- */
-function normalizeAction(action: ContextMenuAction): NativeAction {
-  return {
-    id: action.id,
-    title: action.title,
-    subtitle: action.subtitle,
-    image: action.image,
-    imageColor: action.imageColor,
-    attributes: action.attributes
-      ? {
-          destructive: action.attributes.destructive ? 'true' : 'false',
-          disabled: action.attributes.disabled ? 'true' : 'false',
-          hidden: action.attributes.hidden ? 'true' : 'false',
-        }
-      : undefined,
-    state: action.state,
-    subactions: action.subactions?.map(normalizeSubaction),
-  };
-}
-
 export function ContextMenu(props: ContextMenuProps): React.ReactElement {
   const {
     style,
@@ -147,16 +92,18 @@ export function ContextMenu(props: ContextMenuProps): React.ReactElement {
     actions,
     disabled,
     trigger = 'longPress',
+    haptics,
     onPressAction,
     onMenuOpen,
     onMenuClose,
+    onPreviewPress,
     children,
     ios,
     android,
     ...viewProps
   } = props;
 
-  const nativeActions = useMemo(() => actions.map(normalizeAction), [actions]);
+  const nativeActions = useMemo(() => flattenMenuActions(actions), [actions]);
 
   const handlePressAction = useCallback(
     (e: { nativeEvent: ContextMenuPressActionEvent }) => {
@@ -174,6 +121,10 @@ export function ContextMenu(props: ContextMenuProps): React.ReactElement {
     onMenuClose?.();
   }, [onMenuClose]);
 
+  const handlePreviewPress = useCallback(() => {
+    onPreviewPress?.();
+  }, [onPreviewPress]);
+
   const nativeIOS = useMemo(() => {
     if (!ios) return undefined;
     return {
@@ -196,9 +147,11 @@ export function ContextMenu(props: ContextMenuProps): React.ReactElement {
       actions={nativeActions}
       interactivity={disabled ? 'disabled' : 'enabled'}
       trigger={trigger}
+      haptics={haptics ?? ''}
       onPressAction={onPressAction ? handlePressAction : undefined}
       onMenuOpen={onMenuOpen ? handleMenuOpen : undefined}
       onMenuClose={onMenuClose ? handleMenuClose : undefined}
+      onPreviewPress={onPreviewPress ? handlePreviewPress : undefined}
       ios={nativeIOS}
       android={nativeAndroid}
       {...viewProps}

package/src/ContextMenuNativeComponent.ts

@@ -1,61 +1,48 @@
 // ContextMenuNativeComponent.ts
 import type { HostComponent, ViewProps } from 'react-native';
 import { codegenNativeComponent } from 'react-native';
-import type { BubblingEventHandler } from './codegenTypes';
+import type { BubblingEventHandler, Double, Int32 } from './codegenTypes';
 
 /**
- * Attributes for a context menu action.
+ * One menu item. The JS action tree is flattened (see `menuItems.ts`): each
+ * item points at its parent submenu or section by index, so menus nest to any
+ * depth without a recursive codegen type. Every field is set; empty strings
+ * mean "none" and flags are 'true' | 'false'.
  */
-export type ContextMenuActionAttributes = Readonly<{
-  /** Whether the action is destructive (red styling) */
-  destructive?: string; // 'true' | 'false'
-  /** Whether the action is disabled (grayed out) */
-  disabled?: string; // 'true' | 'false'
-  /** Whether the action is hidden */
-  hidden?: string; // 'true' | 'false'
-}>;
-
-/**
- * A leaf subaction (no further nesting to avoid codegen recursion issues).
- */
-export type ContextMenuSubaction = Readonly<{
+export type ContextMenuItem = Readonly<{
   /** Unique identifier returned in callbacks */
   id: string;
-  /** Display title */
+  /** Display title (a section's header on iOS) */
   title: string;
   /** Secondary text (iOS only) */
-  subtitle?: string;
-  /** Icon name (SF Symbol on iOS, drawable resource on Android) */
-  image?: string;
+  subtitle: string;
+  /** Index of the parent submenu or section; -1 at the top level */
+  parent: Int32;
+  /** 'action' | 'menu' | 'section' */
+  kind: string;
+  /** '' | 'sfSymbol' | 'drawable' | 'image' */
+  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;
-  /** Action attributes */
-  attributes?: ContextMenuActionAttributes;
-  /** Checkmark state: 'off' | 'on' | 'mixed' */
-  state?: string;
-}>;
-
-/**
- * A single action in the context menu.
- * Actions can be nested one level via `subactions` for submenus.
- */
-export type ContextMenuAction = Readonly<{
-  /** Unique identifier returned in callbacks */
-  id: string;
-  /** Display title */
-  title: string;
-  /** Secondary text (iOS only) */
-  subtitle?: string;
-  /** Icon name (SF Symbol on iOS, drawable resource on Android) */
-  image?: string;
-  /** Tint color for the icon (hex string, e.g., "#FF0000") */
-  imageColor?: string;
-  /** Action attributes */
-  attributes?: ContextMenuActionAttributes;
-  /** Checkmark state: 'off' | 'on' | 'mixed' */
-  state?: string;
-  /** Nested actions for submenu (one level deep) */
-  subactions?: ReadonlyArray<ContextMenuSubaction>;
+  imageColor: string;
+  /** 'true' | 'false' */
+  destructive: string;
+  /** 'true' | 'false' */
+  disabled: string;
+  /** 'true' | 'false' (iOS 16+) */
+  keepsMenuPresented: string;
+  /** '' | 'off' | 'on' | 'mixed' */
+  state: string;
+  /** The action's own haptics; '' = the component's */
+  haptics: string;
 }>;
 
 /**
@@ -102,9 +89,9 @@ export interface ContextMenuProps extends ViewProps {
   title?: string;
 
   /**
-   * Menu actions.
+   * Menu items, flattened (see ContextMenuItem).
    */
-  actions: ReadonlyArray<ContextMenuAction>;
+  actions: ReadonlyArray<ContextMenuItem>;
 
   /**
    * Enabled / disabled state.
@@ -118,6 +105,12 @@ export interface ContextMenuProps extends ViewProps {
    */
   trigger?: string; // ContextMenuTrigger
 
+  /**
+   * Haptic played when an action is pressed: '' (none added) | 'none' | 'selection' |
+   * 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error'
+   */
+  haptics?: string;
+
   /**
    * Fired when user presses an action.
    */
@@ -133,6 +126,11 @@ export interface ContextMenuProps extends ViewProps {
    */
   onMenuClose?: BubblingEventHandler<Readonly<{}>>;
 
+  /**
+   * iOS: fired when the user taps the preview (with enablePreview).
+   */
+  onPreviewPress?: BubblingEventHandler<Readonly<{}>>;
+
   ios?: IOSProps;
   android?: AndroidProps;
 }