react-native-platform-components 1.4.0 → 1.6.0

package/src/Button.tsx

@@ -1,10 +1,15 @@
 // Button.tsx
-import React, { useCallback, useMemo } from 'react';
-import type { ColorValue, ViewProps } from 'react-native';
+import React, { useCallback, useMemo, useState } from 'react';
+import type { ColorValue, NativeSyntheticEvent, ViewProps } from 'react-native';
 
-import NativeButton from './ButtonNativeComponent';
+import NativeButton, {
+  type ButtonMenuSelectEvent,
+  type ButtonSelectedChangeEvent,
+} from './ButtonNativeComponent';
 import { resolveIcon, type PlatformIcon } from './icons';
 import { normalizeLabelStyle, type LabelStyle } from './labelStyle';
+import { flattenMenuActions, type ContextMenuAction } from './menuItems';
+import type { Haptics } from './haptics';
 import type { AndroidMaterialStyle } from './sharedTypes';
 
 /**
@@ -17,9 +22,25 @@ import type { AndroidMaterialStyle } from './sharedTypes';
  * | `outlined` | Outlined button                 | `.bordered()`                  |
  * | `text`     | Text button                     | `.plain()`                     |
  * | `elevated` | Elevated button                 | `.gray()`                      |
+ * | `glass`    | Filled tonal button             | `.glass()` (iOS 26+), else `.gray()` |
+ * | `prominentGlass` | Filled button             | `.prominentGlass()` (iOS 26+), else `.filled()` |
+ * | `clearGlass` | Filled tonal button           | `.clearGlass()` (iOS 26+), else `.gray()` |
+ * | `prominentClearGlass` | Filled button        | `.prominentClearGlass()` (iOS 26+), else `.filled()` |
+ *
+ * The glass variants are the iOS 26 Liquid Glass buttons; `color` tints
+ * the prominent glass and `tintColor` colors the label and icon. Clear glass
+ * is more transparent, for buttons over photos and other rich content.
  */
 export type ButtonVariant =
-  'filled' | 'tonal' | 'outlined' | 'text' | 'elevated';
+  | 'filled'
+  | 'tonal'
+  | 'outlined'
+  | 'text'
+  | 'elevated'
+  | 'glass'
+  | 'prominentGlass'
+  | 'clearGlass'
+  | 'prominentClearGlass';
 
 /**
  * Button size. Material 3 Expressive defines five sizes; iOS maps them onto
@@ -33,13 +54,31 @@ export type ButtonSize = 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge';
  */
 export type ButtonShape = 'round' | 'square';
 
+/** Where the icon sits relative to the label. */
+export type ButtonIconPosition = 'leading' | 'trailing' | 'top' | 'bottom';
+
+/**
+ * An animated SF Symbol effect (iOS 17+). `wiggle`, `rotate` and `breathe`
+ * need iOS 18; on earlier versions they do nothing.
+ */
+export type ButtonSymbolEffect =
+  'bounce' | 'pulse' | 'variableColor' | 'wiggle' | 'rotate' | 'breathe';
+
 export interface ButtonProps extends ViewProps {
   /** Button text. Omit for an icon-only button. */
   label?: string;
 
-  /** Icon shown before the label, or alone when there is no label. */
+  /** Icon shown next to the label, or alone when there is no label. */
   icon?: PlatformIcon;
 
+  /**
+   * Where the icon sits relative to the label. Default: `'leading'`.
+   * iOS: `imagePlacement`. Android: `iconGravity` (`textEnd` for trailing,
+   * `textTop` for top). Material has no bottom gravity, so `'bottom'` puts the
+   * icon on top on Android.
+   */
+  iconPosition?: ButtonIconPosition;
+
   /** Emphasis. Default: `'filled'`. See {@link ButtonVariant}. */
   variant?: ButtonVariant;
 
@@ -49,9 +88,24 @@ export interface ButtonProps extends ViewProps {
   /** Corner shape. Default: platform default. */
   shape?: ButtonShape;
 
+  /**
+   * Corner radius in points (dp). Overrides `shape` when set.
+   * iOS: `background.cornerRadius` with the fixed corner style. Android: the
+   * `shapeAppearanceModel` corner size (the press morph is turned off).
+   */
+  cornerRadius?: number;
+
   /** Whether the button is disabled. */
   disabled?: boolean;
 
+  /**
+   * Shows a native spinner in place of the label and icon, keeping the
+   * button's size, and ignores presses. Sets `accessibilityState.busy`.
+   * iOS: `UIButton.Configuration.showsActivityIndicator`. Android: a Material
+   * circular progress indicator drawn as the button icon.
+   */
+  loading?: boolean;
+
   /**
    * Container (background) color.
    * Android: `backgroundTint`. iOS: `baseBackgroundColor`.
@@ -64,15 +118,98 @@ export interface ButtonProps extends ViewProps {
    */
   tintColor?: ColorValue;
 
+  /**
+   * Container color while disabled. Unset keeps the platform's disabled look.
+   * iOS: a `configurationUpdateHandler` on `isEnabled`. Android: the disabled
+   * state of the `backgroundTint` color state list.
+   */
+  disabledColor?: ColorValue;
+
+  /**
+   * Label and icon color while disabled. Unset keeps the platform's disabled
+   * look. iOS: a `configurationUpdateHandler` on `isEnabled`. Android: the
+   * disabled state of the text color and `iconTint` color state lists.
+   */
+  disabledTintColor?: ColorValue;
+
   /** Label font. */
   labelStyle?: LabelStyle;
 
+  /**
+   * Largest scale the label's font can reach with the system text size
+   * (Dynamic Type / font scale), as on `Text`: `undefined` or `0` means no
+   * cap; values of 1 or more cap it.
+   */
+  maxFontSizeMultiplier?: number;
+
   /** Screen-reader label. Defaults to `label`. */
   accessibilityLabel?: string;
 
-  /** Called when the button is pressed. */
+  /**
+   * Haptic played when the user presses the button, flips a toggle or
+   * picks a menu item (not when a menu button opens its menu); not while
+   * `loading` or disabled. Default: none, like the native buttons. See
+   * {@link Haptics}.
+   */
+  haptics?: Haptics;
+
+  /**
+   * Called when the button is pressed. A button with a `menu` opens the menu
+   * instead.
+   */
   onPress?: () => void;
 
+  /**
+   * Makes the button a toggle, with this as its controlled state. A press
+   * calls `onSelectedChange` with the opposite value; the button shows the
+   * new state once `selected` changes, and goes back if it doesn't.
+   *
+   * iOS: `changesSelectionAsPrimaryAction` and `isSelected`, with the
+   * configuration's selected look. Android: a checkable `MaterialButton`
+   * (`isChecked`), with the Material toggle button colors and shape.
+   */
+  selected?: boolean;
+
+  /** Called when a toggle button is pressed, with the state it asks for. */
+  onSelectedChange?: (selected: boolean) => void;
+
+  /**
+   * A menu the button opens when pressed, in place of `onPress`. Same items
+   * as ContextMenu: submenus, sections, icons, states and attributes.
+   *
+   * iOS: `UIButton.menu` with `showsMenuAsPrimaryAction`. Android: a
+   * `PopupMenu` anchored to the button.
+   */
+  menu?: readonly ContextMenuAction[];
+
+  /** Called when a menu item is picked, with its id and title. */
+  onMenuSelect?: (id: string, title: string) => void;
+
+  /** Called when the menu opens. */
+  onMenuOpen?: () => void;
+
+  /** Called when the menu closes. */
+  onMenuClose?: () => void;
+
+  /**
+   * iOS-specific configuration
+   */
+  ios?: {
+    /**
+     * Animates the SF Symbol icon (`UIImageView.addSymbolEffect`, iOS 17+;
+     * `wiggle`, `rotate` and `breathe` need iOS 18). Without
+     * `symbolEffectTrigger` the effect repeats until it is unset. Ignored
+     * for image icons and on Android.
+     */
+    symbolEffect?: ButtonSymbolEffect;
+
+    /**
+     * Plays `symbolEffect` once each time this value changes, instead of
+     * repeating it. The first value doesn't play.
+     */
+    symbolEffectTrigger?: number | string;
+  };
+
   /**
    * Android-specific configuration
    */
@@ -99,16 +236,31 @@ export function Button(props: ButtonProps): React.ReactElement {
   const {
     label,
     icon,
+    iconPosition,
     variant,
     size,
     shape,
+    cornerRadius,
     disabled,
+    loading,
     color,
     tintColor,
+    disabledColor,
+    disabledTintColor,
     labelStyle,
+    maxFontSizeMultiplier,
     accessibilityLabel,
+    haptics,
     onPress,
+    selected,
+    onSelectedChange,
+    menu,
+    onMenuSelect,
+    onMenuOpen,
+    onMenuClose,
+    ios,
     android,
+    accessibilityState,
     ...viewProps
   } = props;
 
@@ -118,26 +270,89 @@ export function Button(props: ButtonProps): React.ReactElement {
     [labelStyle]
   );
 
+  const nativeMenu = useMemo(
+    () => (menu ? flattenMenuActions(menu) : []),
+    [menu]
+  );
+
   const handlePress = useCallback(() => {
+    if (loading) return;
     onPress?.();
-  }, [onPress]);
+  }, [onPress, loading]);
+
+  // Controlled toggle, like React Native's Switch: every press re-renders
+  // with a new event count, so native applies `selected` again and a state
+  // the parent didn't take goes back.
+  const [selectedEventCount, setSelectedEventCount] = useState(0);
+  const handleSelectedChange = useCallback(
+    (e: NativeSyntheticEvent<ButtonSelectedChangeEvent>) => {
+      setSelectedEventCount((count) => count + 1);
+      onSelectedChange?.(e.nativeEvent.selected);
+    },
+    [onSelectedChange]
+  );
+
+  const handleMenuSelect = useCallback(
+    (e: NativeSyntheticEvent<ButtonMenuSelectEvent>) => {
+      onMenuSelect?.(e.nativeEvent.id, e.nativeEvent.title);
+    },
+    [onMenuSelect]
+  );
+
+  const handleMenuOpen = useCallback(() => onMenuOpen?.(), [onMenuOpen]);
+  const handleMenuClose = useCallback(() => onMenuClose?.(), [onMenuClose]);
+
+  const nativeIOS = useMemo(
+    () => ({
+      symbolEffect: ios?.symbolEffect ?? '',
+      symbolEffectTrigger:
+        ios?.symbolEffectTrigger === undefined
+          ? ''
+          : String(ios.symbolEffectTrigger),
+    }),
+    [ios?.symbolEffect, ios?.symbolEffectTrigger]
+  );
+
+  const isToggle = selected !== undefined;
+
+  const mergedAccessibilityState = useMemo(
+    () =>
+      loading ? { ...accessibilityState, busy: true } : accessibilityState,
+    [loading, accessibilityState]
+  );
 
   return (
     <NativeButton
       label={label ?? ''}
       icon={nativeIcon}
+      iconPosition={iconPosition ?? 'leading'}
       variant={variant ?? 'filled'}
       size={size ?? 'small'}
       shape={shape ?? ''}
+      cornerRadius={cornerRadius ?? -1}
       interactivity={disabled ? 'disabled' : 'enabled'}
+      loading={loading ? 'true' : 'false'}
       color={color}
       foregroundColor={tintColor}
+      disabledColor={disabledColor}
+      disabledForegroundColor={disabledTintColor}
       androidRippleColor={android?.rippleColor}
       androidStrokeColor={android?.strokeColor}
       androidMaterial={android?.material ?? 'expressive'}
       labelStyle={nativeLabelStyle}
+      maxFontSizeMultiplier={maxFontSizeMultiplier ?? 0}
       spokenLabel={accessibilityLabel ?? ''}
+      selected={isToggle ? (selected ? 'true' : 'false') : ''}
+      selectedEventCount={selectedEventCount}
+      menu={nativeMenu}
+      ios={nativeIOS}
+      haptics={haptics ?? ''}
       onButtonPress={onPress ? handlePress : undefined}
+      onSelectedChange={isToggle ? handleSelectedChange : undefined}
+      onMenuSelect={onMenuSelect ? handleMenuSelect : undefined}
+      onMenuOpen={onMenuOpen ? handleMenuOpen : undefined}
+      onMenuClose={onMenuClose ? handleMenuClose : undefined}
+      accessibilityState={mergedAccessibilityState}
       {...viewProps}
     />
   );

package/src/ButtonGroup.tsx

@@ -10,6 +10,7 @@ import NativeButtonGroup, {
 } from './ButtonGroupNativeComponent';
 import { resolveIcon, type PlatformIcon } from './icons';
 import { normalizeLabelStyle, type LabelStyle } from './labelStyle';
+import type { Haptics } from './haptics';
 import type { AndroidMaterialStyle } from './sharedTypes';
 
 /**
@@ -21,7 +22,14 @@ import type { AndroidMaterialStyle } from './sharedTypes';
  */
 export type ButtonGroupSelection = 'none' | 'single' | 'multiple';
 
-/** What happens to buttons that don't fit the group's width (Android). */
+/**
+ * What happens to buttons that don't fit the group's width.
+ *
+ * - `none` (default): they are clipped.
+ * - `menu`: the trailing ones move into an overflow menu. Android: the
+ *   `MaterialButtonGroup` overflow menu. iOS: a "…" button with a `UIMenu`.
+ * - `wrap`: they wrap onto more rows (Android only; iOS clips them).
+ */
 export type ButtonGroupOverflow = 'none' | 'menu' | 'wrap';
 
 export interface ButtonGroupButtonProps {
@@ -91,6 +99,19 @@ export interface ButtonGroupProps extends ViewProps {
   /** Label font. */
   labelStyle?: LabelStyle;
 
+  /**
+   * What happens to buttons that don't fit the group's width. Default:
+   * `'none'`. See {@link ButtonGroupOverflow}. A pick from the overflow menu
+   * counts as a press of its button (`onPress`, and the selection).
+   */
+  overflow?: ButtonGroupOverflow;
+
+  /**
+   * Haptic played when a button is pressed, in every selection mode.
+   * Default: none, like the native buttons. See {@link Haptics}.
+   */
+  haptics?: Haptics;
+
   /**
    * Called when a button is pressed, in every selection mode.
    * @param value - The button's value
@@ -108,11 +129,7 @@ export interface ButtonGroupProps extends ViewProps {
    * Android-specific configuration
    */
   android?: {
-    /**
-     * What happens to buttons that don't fit: `'none'` (clipped), `'menu'`
-     * (moved into an overflow menu) or `'wrap'` (wrapped onto more rows).
-     * Default: `'none'`.
-     */
+    /** @deprecated Use the cross-platform `overflow` prop. */
     overflow?: ButtonGroupOverflow;
 
     /** Ripple color shown while pressing a button. */
@@ -148,6 +165,8 @@ export function ButtonGroup(props: ButtonGroupProps): React.ReactElement {
     color,
     tintColor,
     labelStyle,
+    overflow,
+    haptics,
     onPress,
     onSelectionChange,
     android,
@@ -194,11 +213,8 @@ export function ButtonGroup(props: ButtonGroupProps): React.ReactElement {
   );
 
   const nativeAndroid = useMemo(
-    () => ({
-      overflow: android?.overflow ?? 'none',
-      material: android?.material ?? 'expressive',
-    }),
-    [android]
+    () => ({ material: android?.material ?? 'expressive' }),
+    [android?.material]
   );
 
   const isConnected = connected ?? selectionMode !== 'none';
@@ -222,6 +238,8 @@ export function ButtonGroup(props: ButtonGroupProps): React.ReactElement {
       androidRippleColor={android?.rippleColor}
       androidStrokeColor={android?.strokeColor}
       labelStyle={nativeLabelStyle}
+      overflow={overflow ?? android?.overflow ?? 'none'}
+      haptics={haptics ?? ''}
       onButtonPress={onPress ? handlePress : undefined}
       onGroupSelectionChange={
         onSelectionChange ? handleSelectionChange : undefined

package/src/ButtonGroupNativeComponent.ts

@@ -13,6 +13,7 @@ export type ButtonGroupButton = Readonly<{
   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
@@ -46,13 +47,46 @@ export type ButtonGroupLabelStyleProps = Readonly<{
   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<{
-  /** What happens to buttons that don't fit: 'none' | 'menu' | 'wrap' */
-  overflow?: string;
-
   /** Material style: 'm3' | 'expressive' */
   material?: string;
 }>;
@@ -61,7 +95,10 @@ export interface ButtonGroupNativeProps extends ViewProps {
   /** Buttons to display. */
   buttons: ReadonlyArray<ButtonGroupButton>;
 
-  /** 'filled' | 'tonal' | 'outlined' | 'text' | 'elevated' */
+  /**
+   * 'filled' | 'tonal' | 'outlined' | 'text' | 'elevated' | 'glass' |
+   * 'prominentGlass' | 'clearGlass' | 'prominentClearGlass'
+   */
   variant?: string;
 
   /** 'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' */
@@ -103,6 +140,30 @@ export interface ButtonGroupNativeProps extends ViewProps {
   /** 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>;
 
@@ -113,6 +174,15 @@ export interface ButtonGroupNativeProps extends ViewProps {
    */
   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;
 }