react-native-platform-components 1.3.0 → 1.5.0

package/src/DatePicker.tsx

@@ -1,7 +1,7 @@
 // DatePicker.tsx
-import React, { useCallback } from 'react';
+import React, { useCallback, useEffect } from 'react';
 import type { NativeSyntheticEvent, StyleProp, ViewStyle } from 'react-native';
-import { StyleSheet } from 'react-native';
+import { Platform, StyleSheet } from 'react-native';
 
 import NativeDatePicker, {
   type DateChangeEvent,
@@ -16,6 +16,13 @@ import NativeDatePicker, {
 
 import type { AndroidMaterialMode, Visible } from './sharedTypes';
 
+/**
+ * Android: how the Material pickers take input. `'text'` opens the date
+ * picker on its text field and the time picker on its keyboard entry;
+ * `'calendar'` on the calendar and the clock dial. Default: `'calendar'`.
+ */
+export type AndroidDatePickerInputMode = 'calendar' | 'text';
+
 export type DatePickerProps = {
   style?: StyleProp<ViewStyle>;
 
@@ -28,16 +35,38 @@ export type DatePickerProps = {
 
   locale?: string;
   timeZoneName?: string;
+
+  /**
+   * What to pick. `'yearAndMonth'` is `UIDatePicker`'s month and year wheels
+   * (iOS 17.4+; the date wheels before); Android shows the date picker.
+   * `'countDownTimer'` is iOS only (Android shows a date picker).
+   */
   mode?: DatePickerMode;
   presentation?: DatePickerPresentation;
 
+  /**
+   * Forces the 24-hour (`true`) or 12-hour (`false`) clock in the time
+   * modes. Default: the device setting. iOS: the picker's locale with that
+   * hour cycle. Android: the time picker's clock format.
+   */
+  is24Hour?: boolean;
+
   /**
    * Modal only. If presentation !== "modal", ignored.
    * Wrapper ergonomics: boolean.
    */
   visible?: boolean;
 
-  onConfirm?: (dateTime: Date, confirmed: boolean) => void;
+  /**
+   * Called when the selection changes. `confirmed` is true for deliberate
+   * selections (see docs). `durationSeconds` is the selected duration in
+   * `countDownTimer` mode (iOS, and web's time input); 0 in other modes.
+   */
+  onConfirm?: (
+    dateTime: Date,
+    confirmed: boolean,
+    durationSeconds: number
+  ) => void;
   onClosed?: () => void;
 
   /** Test identifier */
@@ -64,6 +93,8 @@ export type DatePickerProps = {
     dialogTitle?: NativeAndroidProps['dialogTitle'];
     positiveButtonTitle?: NativeAndroidProps['positiveButtonTitle'];
     negativeButtonTitle?: NativeAndroidProps['negativeButtonTitle'];
+    /** Material pickers only (`material: 'm3'`). */
+    inputMode?: AndroidDatePickerInputMode;
   };
 };
 
@@ -97,6 +128,7 @@ export function DatePicker(props: DatePickerProps): React.ReactElement {
     mode,
     presentation = 'modal',
     visible,
+    is24Hour,
     onConfirm,
     onClosed,
     ios,
@@ -108,7 +140,8 @@ export function DatePicker(props: DatePickerProps): React.ReactElement {
 
   const handleConfirm = useCallback(
     (e: NativeSyntheticEvent<DateChangeEvent>) => {
-      onConfirm?.(new Date(e.nativeEvent.timestampMs), e.nativeEvent.confirmed);
+      const { timestampMs, confirmed, durationSeconds } = e.nativeEvent;
+      onConfirm?.(new Date(timestampMs), confirmed, durationSeconds ?? 0);
     },
     [onConfirm]
   );
@@ -123,6 +156,7 @@ export function DatePicker(props: DatePickerProps): React.ReactElement {
     mode,
     locale,
     timeZoneName,
+    hourFormat: hourFormat(is24Hour),
 
     presentation,
     visible: normalizeVisible(presentation, visible),
@@ -151,6 +185,7 @@ export function DatePicker(props: DatePickerProps): React.ReactElement {
           dialogTitle: android.dialogTitle,
           positiveButtonTitle: android.positiveButtonTitle,
           negativeButtonTitle: android.negativeButtonTitle,
+          inputMode: android.inputMode,
         }
       : undefined,
   };
@@ -158,6 +193,149 @@ export function DatePicker(props: DatePickerProps): React.ReactElement {
   return <NativeDatePicker testID={testID} {...nativeProps} />;
 }
 
+function hourFormat(is24Hour: boolean | undefined): string {
+  if (is24Hour === undefined) return '';
+  return is24Hour ? '24' : '12';
+}
+
+/** A range of days, as `DateRangePicker` reports it. */
+export type DateRange = { startDate: Date; endDate: Date };
+
+export type DateRangePickerProps = {
+  style?: StyleProp<ViewStyle>;
+
+  /** First day of the range the picker opens with; `null` for none. */
+  startDate?: Date | null;
+
+  /** Last day of the range the picker opens with; `null` for none. */
+  endDate?: Date | null;
+
+  /** Optional bounds. Use `null` for "unbounded". */
+  minDate?: Date | null;
+  maxDate?: Date | null;
+
+  /** Locale of the text-input date format. */
+  locale?: string;
+  timeZoneName?: string;
+
+  /** Shows the picker dialog. */
+  visible: boolean;
+
+  /**
+   * Called with the chosen range when the user confirms it. Both dates are
+   * the start (midnight) of their day in `timeZoneName`, or the device time
+   * zone; `endDate` is the last day of the range, inclusive.
+   */
+  onConfirm?: (range: DateRange) => void;
+
+  /** Called when the dialog closes, confirmed or not. */
+  onClosed?: () => void;
+
+  /** Test identifier */
+  testID?: string;
+
+  android?: {
+    firstDayOfWeek?: NativeAndroidProps['firstDayOfWeek'];
+    /** `'text'` opens on the start and end date fields. */
+    inputMode?: AndroidDatePickerInputMode;
+    dialogTitle?: NativeAndroidProps['dialogTitle'];
+    positiveButtonTitle?: NativeAndroidProps['positiveButtonTitle'];
+    negativeButtonTitle?: NativeAndroidProps['negativeButtonTitle'];
+  };
+};
+
+/**
+ * Whether `DateRangePicker` shows anything on this platform. iOS has no
+ * native date range picker; offer two `DatePicker`s there instead.
+ */
+export const isDateRangePickerSupported: boolean = rangePickerSupported();
+
+function rangePickerSupported(): boolean {
+  return Platform.OS !== 'ios';
+}
+
+/**
+ * A date range picker: Material's `MaterialDatePicker.dateRangePicker()` on
+ * Android, a modal dialog. iOS has no native range picker, so it renders
+ * nothing there and warns in development (see `isDateRangePickerSupported`).
+ */
+export function DateRangePicker(
+  props: DateRangePickerProps
+): React.ReactElement | null {
+  const {
+    style,
+    startDate,
+    endDate,
+    minDate,
+    maxDate,
+    locale,
+    timeZoneName,
+    visible,
+    onConfirm,
+    onClosed,
+    android,
+    testID,
+  } = props;
+
+  const supported = rangePickerSupported();
+  useEffect(() => {
+    if (__DEV__ && visible && !supported) {
+      console.warn(
+        'DateRangePicker: iOS has no native date range picker, so nothing is ' +
+          'shown. Check isDateRangePickerSupported and offer two DatePickers ' +
+          'on iOS.'
+      );
+    }
+  }, [visible, supported]);
+
+  const handleConfirm = useCallback(
+    (e: NativeSyntheticEvent<DateChangeEvent>) => {
+      const { timestampMs, endTimestampMs } = e.nativeEvent;
+      onConfirm?.({
+        startDate: new Date(timestampMs),
+        endDate: new Date(endTimestampMs),
+      });
+    },
+    [onConfirm]
+  );
+
+  const handleClosed = useCallback(() => {
+    onClosed?.();
+  }, [onClosed]);
+
+  if (!supported) return null;
+
+  return (
+    <NativeDatePicker
+      testID={testID}
+      style={[styles.picker, style]}
+      mode="dateRange"
+      presentation="modal"
+      visible={visible ? 'open' : 'closed'}
+      locale={locale}
+      timeZoneName={timeZoneName}
+      dateMs={dateToMsOrSentinel(startDate)}
+      endDateMs={dateToMsOrSentinel(endDate)}
+      minDateMs={dateToMsOrSentinel(minDate)}
+      maxDateMs={dateToMsOrSentinel(maxDate)}
+      onConfirm={onConfirm ? handleConfirm : undefined}
+      onClosed={onClosed ? handleClosed : undefined}
+      android={
+        android
+          ? {
+              firstDayOfWeek: android.firstDayOfWeek,
+              material: 'm3',
+              dialogTitle: android.dialogTitle,
+              positiveButtonTitle: android.positiveButtonTitle,
+              negativeButtonTitle: android.negativeButtonTitle,
+              inputMode: android.inputMode,
+            }
+          : undefined
+      }
+    />
+  );
+}
+
 const styles = StyleSheet.create({
   picker: {},
 });

package/src/DatePickerNativeComponent.ts

@@ -13,9 +13,20 @@ export type TimestampMs = Double;
 export type DateChangeEvent = {
   timestampMs: Double;
   confirmed: boolean;
+  /**
+   * iOS `countDownTimer` mode: the selected duration in seconds. 0 in every
+   * other mode and on Android (which has no countdown picker).
+   */
+  durationSeconds: Double;
+  /**
+   * `dateRange` mode (Android): the last day of the range, with
+   * `timestampMs` the first. 0 in every other mode.
+   */
+  endTimestampMs: Double;
 };
 
-export type DatePickerMode = 'date' | 'time' | 'dateAndTime' | 'countDownTimer';
+export type DatePickerMode =
+  'date' | 'time' | 'dateAndTime' | 'countDownTimer' | 'yearAndMonth';
 export type DatePickerPresentation = 'modal' | 'embedded';
 
 export type IOSDatePickerStyle = 'automatic' | 'compact' | 'inline' | 'wheels';
@@ -36,6 +47,7 @@ export type AndroidProps = {
   dialogTitle?: string;
   positiveButtonTitle?: string;
   negativeButtonTitle?: string;
+  inputMode?: string; // '' | 'calendar' | 'text'
 };
 
 export type WebProps = Readonly<{}>;
@@ -48,15 +60,20 @@ export type MacOSProps = Readonly<{}>;
  *   (Allows negative timestamps for pre-1970 dates.)
  */
 export type CommonProps = {
-  mode?: string; // DatePickerMode
+  mode?: string; // DatePickerMode, or 'dateRange' for DateRangePicker
 
   dateMs?: WithDefault<TimestampMs, -9007199254740991>;
+  /** `dateRange` mode: the last day of the range (`dateMs` is the first). */
+  endDateMs?: WithDefault<TimestampMs, -9007199254740991>;
   minDateMs?: WithDefault<TimestampMs, -9007199254740991>;
   maxDateMs?: WithDefault<TimestampMs, -9007199254740991>;
 
   locale?: string;
   timeZoneName?: string;
 
+  /** '' (device setting) | '12' | '24' */
+  hourFormat?: string;
+
   /**
    * Only used when presentation === "modal".
    * Defaults should be applied in JS wrapper (recommended).

package/src/FloatingActionButton.tsx

@@ -0,0 +1,121 @@
+// FloatingActionButton.tsx
+import React, { useCallback, useMemo } from 'react';
+import type { ColorValue, ViewProps } from 'react-native';
+
+import NativeFloatingActionButton from './FloatingActionButtonNativeComponent';
+import type { Haptics } from './haptics';
+import { resolveIcon, type PlatformIcon } from './icons';
+
+/**
+ * Button size.
+ *
+ * | Size      | Android FAB                     | Android extended FAB | iOS          |
+ * | --------- | ------------------------------- | -------------------- | ------------ |
+ * | `small`   | 40dp small FAB (Material 3)     | 56dp small extended  | 44pt circle  |
+ * | `regular` | 56dp FAB                        | 56dp small extended  | 56pt circle  |
+ * | `medium`  | 80dp medium FAB (M3 Expressive) | 80dp medium extended | 80pt circle  |
+ * | `large`   | 96dp large FAB                  | 96dp large extended  | 96pt circle  |
+ *
+ * An extended iOS button is a capsule of the same height.
+ */
+export type FloatingActionButtonSize = 'small' | 'regular' | 'medium' | 'large';
+
+export interface FloatingActionButtonProps extends ViewProps {
+  /** The icon. See {@link PlatformIcon}. */
+  icon: PlatformIcon;
+
+  /**
+   * Label shown next to the icon: the extended FAB. Omit for an icon-only
+   * button, and give it an `accessibilityLabel`.
+   */
+  label?: string;
+
+  /**
+   * Whether a button with a `label` shows it. Default: `true`. Changing it
+   * animates: Android's `extend()` / `shrink()`, a capsule-to-circle
+   * animation on iOS. Ignored without a `label`.
+   */
+  extended?: boolean;
+
+  /** Size. Default: `'regular'`. See {@link FloatingActionButtonSize}. */
+  size?: FloatingActionButtonSize;
+
+  /**
+   * Container color. Android: `backgroundTint` (default: the Material
+   * primary container). iOS: `baseBackgroundColor`, the tint of the
+   * prominent glass (default: the tint color).
+   */
+  color?: ColorValue;
+
+  /**
+   * Icon and label color. Android: the icon tint and text color. iOS:
+   * `baseForegroundColor`.
+   */
+  tintColor?: ColorValue;
+
+  /** Whether the button is disabled. */
+  disabled?: boolean;
+
+  /** Screen-reader label. Defaults to `label`. */
+  accessibilityLabel?: string;
+
+  /**
+   * Haptic played when the button is pressed. Default: none, like the
+   * native buttons. See {@link Haptics}.
+   */
+  haptics?: Haptics;
+
+  /** Called when the button is pressed. */
+  onPress?: () => void;
+
+  /**
+   * The `nativeID` of the ScrollView (or FlatList) whose scrolling shrinks
+   * and extends the button: an extended button shrinks to its icon while
+   * the content scrolls down and extends again scrolling up or back at the
+   * top. Needs a `label`; `extended={false}` keeps it shrunk.
+   */
+  scrollViewNativeID?: string;
+
+  /** Test identifier */
+  testID?: string;
+}
+
+export function FloatingActionButton(
+  props: FloatingActionButtonProps
+): React.ReactElement {
+  const {
+    icon,
+    label,
+    extended,
+    size,
+    color,
+    tintColor,
+    disabled,
+    accessibilityLabel,
+    haptics,
+    onPress,
+    scrollViewNativeID,
+    ...viewProps
+  } = props;
+
+  const nativeIcon = useMemo(() => resolveIcon(icon), [icon]);
+
+  const handlePress = useCallback(() => onPress?.(), [onPress]);
+
+  return (
+    <NativeFloatingActionButton
+      icon={nativeIcon}
+      label={label ?? ''}
+      size={size ?? 'regular'}
+      extended={extended === false ? 'false' : 'true'}
+      color={color}
+      foregroundColor={tintColor}
+      interactivity={disabled ? 'disabled' : 'enabled'}
+      spokenLabel={accessibilityLabel ?? ''}
+      scrollViewNativeID={scrollViewNativeID ?? ''}
+      haptics={haptics ?? ''}
+      onFabPress={onPress ? handlePress : undefined}
+      {...viewProps}
+    />
+  );
+}

package/src/FloatingActionButtonNativeComponent.ts

@@ -0,0 +1,58 @@
+// FloatingActionButtonNativeComponent.ts
+import type { ColorValue, HostComponent, ViewProps } from 'react-native';
+import { codegenNativeComponent } from 'react-native';
+import type { BubblingEventHandler, Double } from './codegenTypes';
+
+/**
+ * Icon fields, pre-resolved on the JS side (see icons.ts).
+ */
+export type FloatingActionButtonIconProps = 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
+}>;
+
+export interface FloatingActionButtonNativeProps extends ViewProps {
+  /** The icon. */
+  icon?: FloatingActionButtonIconProps;
+
+  /** Label of the extended button; empty for an icon-only button. */
+  label?: string;
+
+  /** 'small' | 'regular' | 'medium' | 'large' */
+  size?: string;
+
+  /** 'true' | 'false': a button with a label shows it. */
+  extended?: string;
+
+  /** Container color. */
+  color?: ColorValue;
+
+  /** Icon and label color. */
+  foregroundColor?: ColorValue;
+
+  /** 'enabled' | 'disabled' */
+  interactivity?: string;
+
+  /** Screen-reader label, on the native button; empty = the label. */
+  spokenLabel?: string;
+
+  /** nativeID of the ScrollView whose scrolling shrinks and extends the button. */
+  scrollViewNativeID?: string;
+
+  /**
+   * 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. */
+  onFabPress?: BubblingEventHandler<Readonly<{}>>;
+}
+
+export default codegenNativeComponent<FloatingActionButtonNativeProps>(
+  'PCFloatingActionButton'
+) as HostComponent<FloatingActionButtonNativeProps>;

package/src/FloatingToolbar.tsx

@@ -0,0 +1,164 @@
+// FloatingToolbar.tsx
+import React, { useMemo } from 'react';
+import {
+  Platform,
+  StyleSheet,
+  type ColorValue,
+  type StyleProp,
+  type ViewProps,
+  type ViewStyle,
+} from 'react-native';
+
+import NativeFloatingToolbar from './FloatingToolbarNativeComponent';
+
+/** Glass effect style of the toolbar on iOS 26. */
+export type FloatingToolbarIOSEffect = 'regular' | 'clear';
+
+/** Material 3 color variant of the toolbar on Android. */
+export type FloatingToolbarAndroidVariant = 'standard' | 'vibrant';
+
+/** Scroll edge effect under the toolbar on iOS 26. */
+export type FloatingToolbarScrollEdgeEffect =
+  'automatic' | 'soft' | 'hard' | 'hidden';
+
+export interface FloatingToolbarProps extends ViewProps {
+  /**
+   * Layout direction of the children. Default: `'horizontal'`.
+   */
+  orientation?: 'horizontal' | 'vertical';
+
+  /**
+   * Container color. Default: the platform's toolbar material (Material 3
+   * `surfaceContainer` or `primaryContainer` on Android, Liquid Glass or a
+   * blur on iOS). Use this rather than `style.backgroundColor`, which would
+   * replace the native shape.
+   */
+  color?: ColorValue;
+
+  /**
+   * The `nativeID` of the ScrollView (or FlatList) the toolbar floats over.
+   * The toolbar works out which edge of it it sits on (top or bottom for a
+   * horizontal toolbar, left or right for a vertical one). Needed by
+   * `hideOnScroll` and `ios.scrollEdgeEffect`; on iOS 26 it also gives that
+   * edge the scroll edge effect, shaped around the toolbar.
+   */
+  scrollViewNativeID?: string;
+
+  /**
+   * Slides the toolbar past its edge of the linked ScrollView while the
+   * content scrolls down, and back as it scrolls up or reaches the top (the
+   * motion of Material's `HideViewOnScrollBehavior`, on both platforms).
+   * Needs `scrollViewNativeID`. Default: `false`.
+   */
+  hideOnScroll?: boolean;
+
+  /**
+   * iOS-specific configuration
+   */
+  ios?: {
+    /**
+     * Glass effect style on iOS 26. Older versions use a blur.
+     * Default: `'regular'`.
+     */
+    effect?: FloatingToolbarIOSEffect;
+
+    /**
+     * iOS 26: the glass scales and shimmers under a touch
+     * (`UIGlassEffect.isInteractive`). Default: `false`.
+     */
+    interactive?: boolean;
+
+    /**
+     * iOS 26: the style of the linked ScrollView's edge effect under the
+     * toolbar (`UIScrollEdgeEffect`): `'soft'` fades the content out,
+     * `'hard'` cuts it off with a dividing line, `'hidden'` turns it off.
+     * The ScrollView gets its own values back when the toolbar unlinks.
+     * Default: the ScrollView's own (`'automatic'` unless changed).
+     */
+    scrollEdgeEffect?: FloatingToolbarScrollEdgeEffect;
+  };
+
+  /**
+   * Android-specific configuration
+   */
+  android?: {
+    /**
+     * Material 3 color variant: `'standard'` (surface) or `'vibrant'`
+     * (primary container). Default: `'standard'`.
+     */
+    variant?: FloatingToolbarAndroidVariant;
+  };
+
+  /** The toolbar's actions, usually `Button`s. */
+  children?: React.ReactNode;
+
+  /** Test identifier */
+  testID?: string;
+}
+
+export function FloatingToolbar(
+  props: FloatingToolbarProps
+): React.ReactElement {
+  const {
+    style,
+    orientation,
+    color,
+    scrollViewNativeID,
+    hideOnScroll,
+    ios,
+    android,
+    children,
+    ...viewProps
+  } = props;
+
+  const nativeIos = useMemo(() => {
+    if (Platform.OS !== 'ios' || !ios) return undefined;
+    return {
+      effect: ios.effect ?? 'regular',
+      interactive: ios.interactive ?? false,
+      scrollEdgeEffect: ios.scrollEdgeEffect ?? '',
+    };
+  }, [ios]);
+
+  const nativeAndroid = useMemo(() => {
+    if (Platform.OS !== 'android' || !android) return undefined;
+    return { variant: android.variant ?? 'standard' };
+  }, [android]);
+
+  const mergedStyle = useMemo(
+    (): StyleProp<ViewStyle> => [
+      styles.toolbar,
+      orientation === 'vertical' ? styles.vertical : styles.horizontal,
+      style,
+    ],
+    [orientation, style]
+  );
+
+  return (
+    <NativeFloatingToolbar
+      style={mergedStyle}
+      color={color}
+      scrollViewNativeID={scrollViewNativeID ?? ''}
+      hideOnScroll={hideOnScroll ?? false}
+      ios={nativeIos}
+      android={nativeAndroid}
+      {...viewProps}
+    >
+      {children}
+    </NativeFloatingToolbar>
+  );
+}
+
+// Material 3 floating toolbar: 8dp container padding, 4dp between actions.
+// The capsule shape comes from native.
+const styles = StyleSheet.create({
+  toolbar: {
+    alignSelf: 'center',
+    alignItems: 'center',
+    justifyContent: 'center',
+    padding: 8,
+    gap: 4,
+  },
+  horizontal: { flexDirection: 'row' },
+  vertical: { flexDirection: 'column' },
+});

package/src/FloatingToolbarNativeComponent.ts

@@ -0,0 +1,47 @@
+// FloatingToolbarNativeComponent.ts
+import type { ColorValue, HostComponent, ViewProps } from 'react-native';
+import { codegenNativeComponent } from 'react-native';
+import type { WithDefault } from './codegenTypes';
+
+/**
+ * iOS-specific configuration.
+ */
+export type FloatingToolbarIOSProps = Readonly<{
+  /** Glass effect style on iOS 26: 'regular' | 'clear' */
+  effect?: string;
+
+  /** iOS 26: glass that reacts to touches (UIGlassEffect.isInteractive) */
+  interactive?: WithDefault<boolean, false>;
+
+  /**
+   * iOS 26: the linked scroll view's edge effect under the toolbar:
+   * '' (the scroll view's own) | 'automatic' | 'soft' | 'hard' | 'hidden'
+   */
+  scrollEdgeEffect?: string;
+}>;
+
+/**
+ * Android-specific configuration.
+ */
+export type FloatingToolbarAndroidProps = Readonly<{
+  /** Material color variant: 'standard' | 'vibrant' */
+  variant?: string;
+}>;
+
+export interface FloatingToolbarNativeProps extends ViewProps {
+  /** Container color. Default: the platform's toolbar material. */
+  color?: ColorValue;
+
+  /** nativeID of the ScrollView the toolbar floats over. */
+  scrollViewNativeID?: string;
+
+  /** Slide off the linked ScrollView's edge while its content scrolls down. */
+  hideOnScroll?: WithDefault<boolean, false>;
+
+  ios?: FloatingToolbarIOSProps;
+  android?: FloatingToolbarAndroidProps;
+}
+
+export default codegenNativeComponent<FloatingToolbarNativeProps>(
+  'PCFloatingToolbar'
+) as HostComponent<FloatingToolbarNativeProps>;