react-native-platform-components 1.3.0 → 1.5.0

package/src/SegmentedControl.tsx

@@ -1,14 +1,10 @@
 // SegmentedControl.tsx
 import React, { useCallback, useMemo } from 'react';
 import {
-  Image,
   Platform,
   StyleSheet,
   type ColorValue,
-  type ImageRequireSource,
-  type ImageURISource,
   type StyleProp,
-  type TextStyle,
   type ViewProps,
   type ViewStyle,
 } from 'react-native';
@@ -17,44 +13,29 @@ import NativeSegmentedControl, {
   type SegmentedControlSegment as NativeSegment,
   type SegmentedControlSelectEvent,
 } from './SegmentedControlNativeComponent';
+import {
+  resolveIcon,
+  type PlatformIcon,
+  type PlatformIconSource,
+} from './icons';
+import { normalizeLabelStyle, type LabelStyle } from './labelStyle';
+import type { Haptics } from './haptics';
+import type { AndroidMaterialStyle } from './sharedTypes';
+import { warnSelectionIdentifiers } from './selectionIdentifiers';
 
 // Android: Minimum height to ensure visibility.
 // Fabric's shadow node measurement isn't being called on initial render,
 // so we apply a minHeight that matches Material design touch target guidelines.
 const ANDROID_MIN_HEIGHT = 48;
 
-/**
- * A single icon source.
- *
- * - `string`: shorthand for an SF Symbol name on iOS and a drawable resource
- *   name on Android (the original API).
- * - `{ type: 'sfSymbol' }`: an SF Symbol. iOS only; ignored on Android.
- * - `{ type: 'drawable' }`: a drawable from the app's `res/drawable`.
- *   Android only; ignored on iOS.
- * - `{ type: 'image' }`: an image asset (`require('./icon.png')`) or a
- *   `{ uri }` source. Works on both platforms. Images are drawn as tinted
- *   templates unless `tinted` is `false`.
- */
-export type SegmentedControlIconSource =
-  | string
-  | { type: 'sfSymbol'; name: string }
-  | { type: 'drawable'; name: string }
-  | {
-      type: 'image';
-      source: ImageRequireSource | ImageURISource;
-      tinted?: boolean;
-    };
+/** A single icon source. Alias of {@link PlatformIconSource}. */
+export type SegmentedControlIconSource = PlatformIconSource;
 
 /**
  * An icon for a segment: a single source used on both platforms, or a
- * per-platform pair so callers don't need to branch on `Platform.OS`.
+ * per-platform pair. Alias of {@link PlatformIcon}.
  */
-export type SegmentedControlIcon =
-  | SegmentedControlIconSource
-  | {
-      ios?: SegmentedControlIconSource;
-      android?: SegmentedControlIconSource;
-    };
+export type SegmentedControlIcon = PlatformIcon;
 
 /**
  * How labels and icons combine for segments that have an icon.
@@ -67,15 +48,8 @@ export type SegmentedControlIcon =
  */
 export type SegmentedControlLabelVisibility = 'auto' | 'labeled' | 'unlabeled';
 
-/**
- * Font for segment labels. Each field falls back to the platform default.
- */
-export interface SegmentedControlLabelStyle {
-  fontFamily?: string;
-  fontSize?: number;
-  fontWeight?: TextStyle['fontWeight'];
-  fontStyle?: 'normal' | 'italic';
-}
+/** Font for segment labels. Alias of {@link LabelStyle}. */
+export type SegmentedControlLabelStyle = LabelStyle;
 
 /**
  * Badge colors. Both default to the platform look (red with white text).
@@ -89,7 +63,7 @@ export interface SegmentedControlSegmentProps {
   /** Display label for the segment */
   label: string;
 
-  /** Unique value identifier for the segment */
+  /** Unique, non-empty value identifier for the segment. */
   value: string;
 
   /** Whether this specific segment is disabled */
@@ -110,6 +84,12 @@ export interface SegmentedControlSegmentProps {
    * announced by their title.
    */
   accessibilityLabel?: string;
+
+  /**
+   * Test identifier of the segment, for E2E taps. iOS: the segment's
+   * accessibility element. Android: the segment's button.
+   */
+  testID?: string;
 }
 
 export interface SegmentedControlProps extends ViewProps {
@@ -139,6 +119,13 @@ export interface SegmentedControlProps extends ViewProps {
   /** Whether the entire control is disabled */
   disabled?: boolean;
 
+  /**
+   * Haptic played when the user changes the selection (a tap that selects or
+   * clears a segment), not when `selectedValue` changes. Default: none, like
+   * the native controls. See {@link Haptics}.
+   */
+  haptics?: Haptics;
+
   /**
    * How labels and icons combine. Default: `'auto'`.
    * See {@link SegmentedControlLabelVisibility}.
@@ -160,6 +147,12 @@ export interface SegmentedControlProps extends ViewProps {
   /** Font for segment labels. See {@link SegmentedControlLabelStyle}. */
   labelStyle?: SegmentedControlLabelStyle;
 
+  /**
+   * Largest scale the labels may reach with the system text size (Dynamic
+   * Type / font scale), as on React Native `Text`. Unset or `0`: no cap.
+   */
+  maxFontSizeMultiplier?: number;
+
   /** Colors for segment badges. See {@link SegmentedControlBadgeStyle}. */
   badgeStyle?: SegmentedControlBadgeStyle;
 
@@ -201,77 +194,20 @@ export interface SegmentedControlProps extends ViewProps {
 
     /** Outline color of the segments. */
     strokeColor?: ColorValue;
+
+    /**
+     * Material style: the Material 3 Expressive connected buttons (default),
+     * or the classic Material 3 segmented buttons.
+     */
+    material?: AndroidMaterialStyle;
   };
 
   /** Test identifier */
   testID?: string;
 }
 
-type NativeIconFields = Pick<
-  NativeSegment,
-  'iconType' | 'iconName' | 'iconUri' | 'iconScale' | 'iconTinted'
->;
-
-const NO_ICON: NativeIconFields = {
-  iconType: '',
-  iconName: '',
-  iconUri: '',
-  iconScale: 1,
-  iconTinted: 'true',
-};
-
-function pickIconSource(
-  icon: SegmentedControlIcon | undefined
-): SegmentedControlIconSource | undefined {
-  if (icon === undefined || typeof icon === 'string' || 'type' in icon) {
-    return icon;
-  }
-  return Platform.OS === 'ios' ? icon.ios : icon.android;
-}
-
-/**
- * Flattens the public icon shape into the strings native expects, dropping
- * sources that don't apply to the current platform.
- */
-export function resolveSegmentIcon(
-  icon: SegmentedControlIcon | undefined
-): NativeIconFields {
-  const source = pickIconSource(icon);
-  if (source === undefined) return NO_ICON;
-
-  if (typeof source === 'string') {
-    if (source.length === 0) return NO_ICON;
-    return {
-      ...NO_ICON,
-      iconType: Platform.OS === 'ios' ? 'sfSymbol' : 'drawable',
-      iconName: source,
-    };
-  }
-
-  switch (source.type) {
-    case 'sfSymbol':
-      return Platform.OS === 'ios'
-        ? { ...NO_ICON, iconType: 'sfSymbol', iconName: source.name }
-        : NO_ICON;
-    case 'drawable':
-      return Platform.OS === 'android'
-        ? { ...NO_ICON, iconType: 'drawable', iconName: source.name }
-        : NO_ICON;
-    case 'image': {
-      const resolved = Image.resolveAssetSource(source.source);
-      if (!resolved?.uri) return NO_ICON;
-      return {
-        iconType: 'image',
-        iconName: '',
-        iconUri: resolved.uri,
-        iconScale: resolved.scale > 0 ? resolved.scale : 1,
-        iconTinted: source.tinted === false ? 'false' : 'true',
-      };
-    }
-    default:
-      return NO_ICON;
-  }
-}
+/** Flattens a segment icon for native. Alias of {@link resolveIcon}. */
+export const resolveSegmentIcon = resolveIcon;
 
 function normalizeSelectedValue(selected: string | null): string {
   return selected ?? '';
@@ -290,7 +226,9 @@ export function SegmentedControl(
     activeTintColor,
     inactiveTintColor,
     labelStyle,
+    maxFontSizeMultiplier,
     badgeStyle,
+    haptics,
     onSelect,
     onDeselect,
     ios,
@@ -300,6 +238,10 @@ export function SegmentedControl(
 
   // Normalize segments for native
   const nativeSegments = useMemo((): NativeSegment[] => {
+    warnSelectionIdentifiers(
+      'SegmentedControl',
+      segments.map((segment) => segment.value)
+    );
     return segments.map((seg) => ({
       label: seg.label,
       value: seg.value,
@@ -307,6 +249,7 @@ export function SegmentedControl(
       badge:
         seg.badge === undefined || seg.badge === null ? '' : String(seg.badge),
       accessibilityLabel: seg.accessibilityLabel ?? '',
+      testID: seg.testID ?? '',
       ...resolveSegmentIcon(seg.icon),
     }));
   }, [segments]);
@@ -346,24 +289,17 @@ export function SegmentedControl(
     (Platform.OS === 'ios' ? ios?.selectedSegmentTintColor : undefined);
 
   // Normalize the label font; empty / 0 means platform default
-  const nativeLabelStyle = useMemo(() => {
-    if (!labelStyle) return undefined;
-    return {
-      fontFamily: labelStyle.fontFamily ?? '',
-      fontSize: labelStyle.fontSize ?? 0,
-      fontWeight:
-        labelStyle.fontWeight === undefined
-          ? ''
-          : String(labelStyle.fontWeight),
-      fontStyle: labelStyle.fontStyle ?? '',
-    };
-  }, [labelStyle]);
+  const nativeLabelStyle = useMemo(
+    () => normalizeLabelStyle(labelStyle),
+    [labelStyle]
+  );
 
   // Normalize Android props
   const nativeAndroid = useMemo(() => {
     if (!android) return undefined;
     return {
       selectionRequired: android.selectionRequired === false ? 'false' : 'true',
+      material: android.material ?? 'expressive',
     };
   }, [android]);
 
@@ -388,8 +324,10 @@ export function SegmentedControl(
       androidRippleColor={android?.rippleColor}
       androidStrokeColor={android?.strokeColor}
       labelStyle={nativeLabelStyle}
+      maxFontSizeMultiplier={maxFontSizeMultiplier ?? 0}
       badgeBackgroundColor={badgeStyle?.backgroundColor}
       badgeTextColor={badgeStyle?.color}
+      haptics={haptics ?? ''}
       onSelect={onSelect || onDeselect ? handleSelect : undefined}
       ios={nativeIos}
       android={nativeAndroid}

package/src/SegmentedControlNativeComponent.ts

@@ -21,11 +21,13 @@ export type SegmentedControlSegment = 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
   badge: string; // Badge text, empty = no badge
   accessibilityLabel: string; // Screen-reader label, empty = use label
+  testID: string; // E2E identifier of the segment, empty = none
 }>;
 
 /**
@@ -72,6 +74,9 @@ export type IOSProps = Readonly<{
 export type AndroidProps = Readonly<{
   /** Whether one segment must always be selected */
   selectionRequired?: string; // 'true' | 'false'
+
+  /** Material style: 'm3' | 'expressive' */
+  material?: string;
 }>;
 
 export interface SegmentedControlProps extends ViewProps {
@@ -114,12 +119,21 @@ export interface SegmentedControlProps extends ViewProps {
   /** Label font. */
   labelStyle?: LabelStyleProps;
 
+  /** Largest font scale the labels may reach; 0 = no cap. */
+  maxFontSizeMultiplier?: Double;
+
   /** Badge background (default: system red). */
   badgeBackgroundColor?: ColorValue;
 
   /** Badge text color (default: white). */
   badgeTextColor?: ColorValue;
 
+  /**
+   * Haptic played when the user changes the selection: '' (none added) | 'none' | 'selection' |
+   * 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error'
+   */
+  haptics?: string;
+
   /**
    * Fired when the user selects a segment.
    */

package/src/SelectionMenu.tsx

@@ -3,14 +3,44 @@ import React, { useCallback, useMemo } from 'react';
 import { Platform, type ViewProps } from 'react-native';
 
 import NativeSelectionMenu, {
-  type SelectionMenuOption,
+  type SelectionMenuNativeOption,
   type SelectionMenuSelectEvent,
 } from './SelectionMenuNativeComponent';
+import { resolveIcon, type PlatformIcon } from './icons';
+import { warnSelectionIdentifiers } from './selectionIdentifiers';
 
-export type { SelectionMenuOption };
-
+import type { Haptics } from './haptics';
 import type { AndroidMaterialMode, Presentation } from './sharedTypes';
 
+/**
+ * A single option: a label and its data payload, with an optional icon and
+ * second line.
+ */
+export interface SelectionMenuOption {
+  /** Display text */
+  label: string;
+  /** Unique, non-empty payload returned by `onSelect` and matched by `selected`. */
+  data: string;
+  /** Keeps the option visible but prevents the user from choosing it. */
+  disabled?: boolean;
+  /**
+   * Secondary text under the label.
+   * - iOS: `UIAction.subtitle` in the system menu.
+   * - Android: a second line in the rows of the embedded `m3` dropdown.
+   *   The modal `PopupMenu` and the `system` Spinner have one line per item,
+   *   so it's not shown there.
+   */
+  subtitle?: string;
+  /**
+   * Icon next to the label. See {@link PlatformIcon}.
+   * - iOS: `UIAction.image`.
+   * - Android: the modal `PopupMenu` item icon and a leading icon in the
+   *   rows of the embedded `m3` dropdown. The `system` Spinner shows labels
+   *   only.
+   */
+  icon?: PlatformIcon;
+}
+
 export interface SelectionMenuProps extends ViewProps {
   /** Options are label + data (payload) */
   options: readonly SelectionMenuOption[];
@@ -37,6 +67,12 @@ export interface SelectionMenuProps extends ViewProps {
    */
   visible?: boolean;
 
+  /**
+   * Haptic played when the user picks an option. Default: none beyond the
+   * system menu's own feedback. See {@link Haptics}.
+   */
+  haptics?: Haptics;
+
   /**
    * Called when the user selects an option.
    * Receives the selected `data` payload, plus label/index for convenience.
@@ -56,12 +92,38 @@ export interface SelectionMenuProps extends ViewProps {
   android?: {
     /** Material preference ('system' | 'm3'). */
     material?: AndroidMaterialMode;
+    /**
+     * Embedded `m3` dropdown only: the field accepts typing and filters the
+     * options by label (case-insensitive prefix of the label or of any word
+     * in it). Picking an option still goes through `onSelect`, and `selected`
+     * stays the source of truth: when the field loses focus, its text goes
+     * back to the selected option's label (or empty, showing the
+     * placeholder). Default `false`.
+     */
+    searchable?: boolean;
   };
 
   /** Test identifier */
   testID?: string;
 }
 
+/** Flattens options for native: icons resolved, every field set. */
+function normalizeSelectionMenuOptions(
+  options: readonly SelectionMenuOption[]
+): SelectionMenuNativeOption[] {
+  warnSelectionIdentifiers(
+    'SelectionMenu',
+    options.map((option) => option.data)
+  );
+  return options.map((option) => ({
+    label: option.label,
+    data: option.data,
+    disabled: option.disabled ? 'true' : 'false',
+    subtitle: option.subtitle ?? '',
+    ...resolveIcon(option.icon),
+  }));
+}
+
 function normalizeSelectedData(selected: string | null): string {
   return selected ?? '';
 }
@@ -84,6 +146,7 @@ export function SelectionMenu(props: SelectionMenuProps): React.ReactElement {
     placeholder,
     presentation = 'modal',
     visible,
+    haptics,
     onSelect,
     onRequestClose,
     ios,
@@ -96,6 +159,11 @@ export function SelectionMenu(props: SelectionMenuProps): React.ReactElement {
     [selected]
   );
 
+  const nativeOptions = useMemo(
+    () => normalizeSelectionMenuOptions(options),
+    [options]
+  );
+
   const nativeVisible = useMemo(
     () => normalizeNativeVisible(presentation, visible),
     [presentation, visible]
@@ -104,9 +172,12 @@ export function SelectionMenu(props: SelectionMenuProps): React.ReactElement {
   const handleSelect = useCallback(
     (e: { nativeEvent: SelectionMenuSelectEvent }) => {
       const { index, label, data } = e.nativeEvent;
+      const option = options[index];
+      if (disabled || !option || option.disabled || option.data !== data)
+        return;
       onSelect?.(data, label, index);
     },
-    [onSelect]
+    [disabled, onSelect, options]
   );
 
   const handleRequestClose = useCallback(() => {
@@ -116,7 +187,10 @@ export function SelectionMenu(props: SelectionMenuProps): React.ReactElement {
   // Keep android prop stable and codegen-friendly (string unions live in native spec).
   const nativeAndroid = useMemo(() => {
     if (!android) return undefined;
-    return { material: android.material };
+    return {
+      material: android.material,
+      searchable: android.searchable ? 'true' : 'false',
+    };
   }, [android]);
 
   // On Android, force a fresh native view when structural props change so the
@@ -130,12 +204,13 @@ export function SelectionMenu(props: SelectionMenuProps): React.ReactElement {
     <NativeSelectionMenu
       key={remountKey}
       style={style}
-      options={options}
+      options={nativeOptions}
       selectedData={selectedData}
       interactivity={disabled ? 'disabled' : 'enabled'}
       placeholder={placeholder}
       anchorMode={presentation === 'embedded' ? 'inline' : 'headless'}
       visible={nativeVisible}
+      haptics={haptics ?? ''}
       onSelect={onSelect ? handleSelect : undefined}
       onRequestClose={onRequestClose ? handleRequestClose : undefined}
       ios={ios}

package/src/SelectionMenuNativeComponent.ts

@@ -1,14 +1,28 @@
 // SelectionMenuNativeComponent.ts
 import type { HostComponent, ViewProps } from 'react-native';
 import { codegenNativeComponent } from 'react-native';
-import type { BubblingEventHandler, Int32, WithDefault } from './codegenTypes';
+import type {
+  BubblingEventHandler,
+  Double,
+  Int32,
+  WithDefault,
+} from './codegenTypes';
 
 /**
- * A single option in the menu.
+ * A single option in the menu. Icons are pre-resolved on the JS side (see
+ * icons.ts); empty strings mean "none".
  */
-export type SelectionMenuOption = Readonly<{
+export type SelectionMenuNativeOption = Readonly<{
   label: string;
   data: string;
+  disabled: string; // 'true' | 'false'
+  subtitle: string;
+  iconType: string; // '' | 'sfSymbol' | 'drawable' | 'image'
+  iconName: string;
+  iconRequest: string;
+  iconUri: string;
+  iconScale: Double;
+  iconTinted: string; // 'true' | 'false'
 }>;
 
 /**
@@ -44,13 +58,15 @@ export type IOSProps = Readonly<{}>;
  */
 export type AndroidProps = Readonly<{
   material?: string; // AndroidMaterialMode
+  /** Embedded M3 dropdown: accept typing to filter the options */
+  searchable?: string; // 'true' | 'false'
 }>;
 
 export interface SelectionMenuProps extends ViewProps {
   /**
    * Menu options.
    */
-  options: ReadonlyArray<SelectionMenuOption>;
+  options: ReadonlyArray<SelectionMenuNativeOption>;
 
   /**
    * Controlled selection by `data`.
@@ -81,6 +97,12 @@ export interface SelectionMenuProps extends ViewProps {
    */
   visible?: string; // SelectionMenuVisible
 
+  /**
+   * Haptic played when the user picks an option: '' (none added) | 'none' | 'selection' |
+   * 'light' | 'medium' | 'heavy' | 'success' | 'warning' | 'error'
+   */
+  haptics?: string;
+
   /**
    * Fired when the user selects an option.
    */