@amazon-devices/react-native-screens 2.0.1759135970 → 3.0.9000000000

package/src/types.tsx

@@ -1,17 +1,6 @@
-/*
- * Portions of this file are copyright (c) 2023 Amazon.com, Inc. or its affiliates.  All rights reserved.
- *
- * PORTIONS OF THIS FILE ARE AMAZON PROPRIETARY/CONFIDENTIAL.  USE IS SUBJECT TO LICENSE TERMS.
- *
- * Amazon modifications are indicated by [amznmod_* comments].
- */
-
-/*
- * Changelog:
- * Set up react-native-screens package to build for Kepler
- */
-
+import React from 'react';
 import {
+  Animated,
   NativeSyntheticEvent,
   ViewProps,
   View,
@@ -19,6 +8,7 @@ import {
   TextInputFocusEventData,
   ColorValue,
 } from 'react-native';
+import { NativeStackNavigatorProps } from './native-stack/types';
 
 export type SearchBarCommands = {
   focus: () => void;
@@ -26,8 +16,10 @@ export type SearchBarCommands = {
   clearText: () => void;
   toggleCancelButton: (show: boolean) => void;
   setText: (text: string) => void;
+  cancelSearch: () => void;
 };
 
+export type BackButtonDisplayMode = 'default' | 'generic' | 'minimal';
 export type StackPresentationTypes =
   | 'push'
   | 'modal'
@@ -45,8 +37,11 @@ export type StackAnimationTypes =
   | 'simple_push'
   | 'slide_from_bottom'
   | 'slide_from_right'
-  | 'slide_from_left';
+  | 'slide_from_left'
+  | 'ios_from_right'
+  | 'ios_from_left';
 export type BlurEffectTypes =
+  | 'none'
   | 'extraLight'
   | 'light'
   | 'dark'
@@ -102,12 +97,15 @@ export type GestureResponseDistanceType = {
   bottom?: number;
 };
 
-export type SheetDetentTypes = 'medium' | 'large' | 'all';
 export type SearchBarPlacement = 'automatic' | 'inline' | 'stacked';
 
 export interface ScreenProps extends ViewProps {
-  active?: 0 | 1 ;
-  activityState?: 0 | 1 | 2;
+  active?: 0 | 1 | Animated.AnimatedInterpolation<number>;
+  activityState?: 0 | 1 | 2 | Animated.AnimatedInterpolation<number>;
+  /**
+   * Boolean indicating that the screen should be frozen with `react-freeze`.
+   */
+  shouldFreeze?: boolean;
   children?: React.ReactNode;
   /**
    * Boolean indicating that swipe dismissal should trigger animation provided by `stackAnimation`. Defaults to `false`.
@@ -123,6 +121,10 @@ export interface ScreenProps extends ViewProps {
    * Internal boolean used to not attach events used only by native-stack. It prevents non native-stack navigators from sending transition progress from their Screen components.
    */
   isNativeStack?: boolean;
+  /**
+   * Internal boolean used to detect if current header has large title on iOS.
+   */
+  hasLargeHeader?: boolean;
   /**
    * Whether inactive screens should be suspended from re-rendering. Defaults to `false`.
    * When `enableFreeze()` is run at the top of the application defaults to `true`.
@@ -136,6 +138,16 @@ export interface ScreenProps extends ViewProps {
    * @platform ios
    */
   fullScreenSwipeEnabled?: boolean;
+  /**
+   * Whether the full screen dismiss gesture has shadow under view during transition.
+   * When enabled, a custom shadow view is added during the transition which tries to mimic the
+   * default iOS shadow. Defaults to `true`.
+   *
+   * This does not affect the behavior of transitions that don't use gestures, enabled by `fullScreenGestureEnabled` prop.
+   *
+   * @platform ios
+   */
+  fullScreenSwipeShadowEnabled?: boolean;
   /**
    * Whether you can use gestures to dismiss this screen. Defaults to `true`.
    *
@@ -174,6 +186,12 @@ export interface ScreenProps extends ViewProps {
    * @platform android
    */
   navigationBarColor?: ColorValue;
+  /**
+   * Boolean indicating whether the content should be visible behind the navigation bar. Defaults to `false`.
+   *
+   * @platform android
+   */
+  navigationBarTranslucent?: boolean;
   /**
    * Sets the visibility of the navigation bar. Defaults to `false`.
    *
@@ -198,7 +216,7 @@ export interface ScreenProps extends ViewProps {
    * A callback that gets called when the header height has changed.
    */
   onHeaderHeightChange?: (
-    e: NativeSyntheticEvent<HeaderHeightChangeEventType>
+    e: NativeSyntheticEvent<HeaderHeightChangeEventType>,
   ) => void;
   /**
    * A callback that gets called after swipe back is canceled.
@@ -216,13 +234,19 @@ export interface ScreenProps extends ViewProps {
    * @platform ios
    */
   onNativeDismissCancelled?: (
-    e: NativeSyntheticEvent<{ dismissCount: number }>
+    e: NativeSyntheticEvent<{ dismissCount: number }>,
+  ) => void;
+  /**
+   * A callback that gets called when the current screen is in `formSheet` presentation and its detent has changed.
+   */
+  onSheetDetentChanged?: (
+    e: NativeSyntheticEvent<{ index: number; isStable: boolean }>,
   ) => void;
   /**
    * An internal callback called every frame during the transition of screens of `native-stack`, used to feed transition context.
    */
   onTransitionProgress?: (
-    e: NativeSyntheticEvent<TransitionProgressEventType>
+    e: NativeSyntheticEvent<TransitionProgressEventType>,
   ) => void;
   /**
    * A callback that gets called when the current screen will appear. This is called as soon as the transition begins.
@@ -262,18 +286,41 @@ export interface ScreenProps extends ViewProps {
   screenOrientation?: ScreenOrientationTypes;
   /**
    * Describes heights where a sheet can rest.
-   * Works only when `stackPresentation` is set to `formSheet`.
-   * Defaults to `large`.
+   * Works only when `presentation` is set to `formSheet`.
    *
-   * Available values:
+   * Heights should be described as fraction (a number from `[0, 1]` interval) of screen height / maximum detent height.
+   * You can pass an array of ascending values each defining allowed sheet detent. iOS accepts any number of detents,
+   * while **Android is limited to three**.
    *
-   * - `large` - only large detent level will be allowed
-   * - `medium` - only medium detent level will be allowed
-   * - `all` - all detent levels will be allowed
+   * There is also possibility to specify `fitToContents` literal, which intents to set the sheet height
+   * to the height of its contents.
    *
-   * @platform ios
+   * Please note that the array **must** be sorted in ascending order. This invariant is verified only in developement mode,
+   * where violation results in error.
+   *
+   * **Android is limited to up 3 values in the array** -- any surplus values, beside first three are ignored.
+   *
+   * There are also legacy & **deprecated** options available:
+   *
+   * * 'medium' - corresponds to `[0.5]` detent value, around half of the screen height,
+   * * 'large' - corresponds to `[1.0]` detent value, maximum height,
+   * * 'all' - corresponds to `[0.5, 1.0]` value, the name is deceiving due to compatibility reasons.
+   *
+   * These are provided solely for **temporary** backward compatibility and are destined for removal in future versions.
+   *
+   * Defaults to `[1.0]`.
    */
-  sheetAllowedDetents?: SheetDetentTypes;
+  sheetAllowedDetents?: number[] | 'fitToContents' | 'medium' | 'large' | 'all';
+  /**
+   * Integer value describing elevation of the sheet, impacting shadow on the top edge of the sheet.
+   *
+   * Not dynamic - changing it after the component is rendered won't have an effect.
+   *
+   * Defaults to `24`.
+   *
+   * @platform Android
+   */
+  sheetElevation?: number;
   /**
    * Whether the sheet should expand to larger detent when scrolling.
    * Works only when `stackPresentation` is set to `formSheet`.
@@ -305,17 +352,43 @@ export interface ScreenProps extends ViewProps {
    * The largest sheet detent for which a view underneath won't be dimmed.
    * Works only when `stackPresentation` is set to `formSheet`.
    *
-   * If this prop is set to:
+   * This prop can be set to an number, which indicates index of detent in `sheetAllowedDetents` array for which
+   * there won't be a dimming view beneath the sheet.
    *
-   * - `large` - the view underneath won't be dimmed at any detent level
-   * - `medium` - the view underneath will be dimmed only when detent level is `large`
-   * - `all` - the view underneath will be dimmed for any detent level
+   * If the specified index is out of bounds of `sheetAllowedDetents` array, in dev environment mode error will be thrown,
+   * in production the value will be reset to default value.
    *
-   * Defaults to `all`.
+   * Additionaly there are following options available:
    *
-   * @platform ios
+   * * `none` - there will be dimming view for all detents levels,
+   * * `last` - there won't be a dimming view for any detent level.
+   *
+   * There also legacy & **deprecated** prop values available: `medium`, `large` (don't confuse with `largest`), `all`, which work in tandem with
+   * corresponding legacy prop values for `sheetAllowedDetents` prop.
+   *
+   * These are provided solely for **temporary** backward compatibility and are destined for removal in future versions.
+   *
+   * Defaults to `none`, indicating that the dimming view should be always present.
    */
-  sheetLargestUndimmedDetent?: SheetDetentTypes;
+  sheetLargestUndimmedDetentIndex?:
+    | number
+    | 'none'
+    | 'last'
+    | 'medium' // deprecated
+    | 'large' // deprecated
+    | 'all'; // deprecated
+  /**
+   * Index of the detent the sheet should expand to after being opened.
+   * Works only when `stackPresentation` is set to `formSheet`.
+   *
+   * If the specified index is out of bounds of `sheetAllowedDetents` array, in dev environment more error will be thrown,
+   * in production the value will be reset to default value.
+   *
+   * Additionaly there is `last` value available, when set the sheet will expand initially to last (largest) detent.
+   *
+   * Defaults to `0` - which represents first detent in the detents array.
+   */
+  sheetInitialDetentIndex?: number | 'last';
   /**
    * How the screen should appear/disappear when pushed or popped at the top of the stack.
    * The following values are currently supported:
@@ -323,10 +396,12 @@ export interface ScreenProps extends ViewProps {
    * - "fade" – fades screen in or out
    * - "fade_from_bottom" – performs a fade from bottom animation
    * - "flip" – flips the screen, requires stackPresentation: "modal" (iOS only)
-   * - "simple_push" – performs a default animation, but without shadow and native header transition (iOS only)
+   * - "simple_push" – performs a default animation, but without native header transition (iOS only)
    * - `slide_from_bottom` – performs a slide from bottom animation
    * - "slide_from_right" - slide in the new screen from right to left (Android only, resolves to default transition on iOS)
-   * - "slide_from_left" - slide in the new screen from left to right (Android only, resolves to default transition on iOS)
+   * - "slide_from_left" - slide in the new screen from left to right
+   * - "ios_from_right" - iOS like slide in animation. pushes in the new screen from right to left (Android only, resolves to default transition on iOS)
+   * - "ios_from_left" - iOS like slide in animation. pushes in the new screen from left to right (Android only, resolves to default transition on iOS)
    * - "none" – the screen appears/dissapears without an animation
    */
   stackAnimation?: StackAnimationTypes;
@@ -377,12 +452,25 @@ export interface ScreenProps extends ViewProps {
    */
   swipeDirection?: SwipeDirectionTypes;
   /**
-   * Changes the duration (in milliseconds) of `slide_from_bottom`, `fade_from_bottom`, `fade` and `simple_push` transitions on iOS. Defaults to `350`.
+   * Changes the duration (in milliseconds) of `slide_from_bottom`, `fade_from_bottom`, `fade` and `simple_push` transitions on iOS. Defaults to `500`.
    * The duration of `default` and `flip` transitions isn't customizable.
    *
    * @platform ios
    */
   transitionDuration?: number;
+  /**
+   * Footer component that can be used alongside formSheet stack presentation style.
+   *
+   * This option is provided, because due to implementation details it might be problematic
+   * to implement such layout with JS-only code.
+   *
+   * Please note that this prop is marked as unstable and might be subject of breaking changes,
+   * including removal, in particular when we find solution that will make implementing it with JS
+   * straightforward.
+   *
+   * @platform android
+   */
+  unstable_sheetFooter?: () => React.ReactNode;
 }
 
 export interface ScreenContainerProps extends ViewProps {
@@ -397,12 +485,19 @@ export interface ScreenContainerProps extends ViewProps {
   hasTwoStates?: boolean;
 }
 
-export interface ScreenStackProps extends ViewProps {
+export interface GestureDetectorBridge {
+  stackUseEffectCallback: (
+    stackRef: React.MutableRefObject<React.Ref<NativeStackNavigatorProps>>,
+  ) => void;
+}
+
+export interface ScreenStackProps extends ViewProps, GestureProps {
   children?: React.ReactNode;
   /**
    * A callback that gets called when the current screen finishes its transition.
    */
   onFinishTransitioning?: (e: NativeSyntheticEvent<TargetedEvent>) => void;
+  ref?: React.MutableRefObject<React.Ref<View>>;
 }
 
 export interface ScreenStackHeaderConfigProps extends ViewProps {
@@ -456,6 +551,15 @@ export interface ScreenStackHeaderConfigProps extends ViewProps {
    * @platform ios
    */
   disableBackButtonMenu?: boolean;
+  /**
+   * How the back button behaves by default (when not customized). Available on iOS>=14, and is used only when none of: `backTitleFontFamily`, `backTitleFontSize`, `disableBackButtonMenu` or `backTitle` is set.
+   * The following values are currently supported (they correspond to https://developer.apple.com/documentation/uikit/uinavigationitembackbuttondisplaymode?language=objc):
+   * - "default" – show given back button previous controller title, system generic or just icon based on available space
+   * - "generic" – show given system generic or just icon based on available space
+   * - "minimal" – show just an icon
+   * @platform ios
+   */
+  backButtonDisplayMode?: BackButtonDisplayMode;
   /**
    * When set to true the header will be hidden while the parent Screen is on the top of the stack. The default value is false.
    */
@@ -558,6 +662,7 @@ export interface SearchBarProps {
    * * `blur` - removes focus from the search bar
    * * `clearText` - removes any text present in the search bar input field
    * * `setText` - sets the search bar's content to given value
+   * * `cancelSearch` - cancel search in search bar.
    * * `toggleCancelButton` - depending on passed boolean value, hides or shows cancel button (iOS only)
    */
   ref?: React.RefObject<SearchBarCommands>;
@@ -653,7 +758,7 @@ export interface SearchBarProps {
    * A callback that gets called when the search button is pressed. It receives the current text value of the search bar.
    */
   onSearchButtonPress?: (
-    e: NativeSyntheticEvent<TextInputFocusEventData>
+    e: NativeSyntheticEvent<TextInputFocusEventData>,
   ) => void;
   /**
    * Text displayed when search field is empty
@@ -697,3 +802,68 @@ export interface SearchBarProps {
    */
   shouldShowHintSearchIcon?: boolean;
 }
+
+/**
+ * Custom Screen Transition
+ */
+
+/**
+ * copy from GestureHandler to avoid strong dependency
+ */
+export type PanGestureHandlerEventPayload = {
+  x: number;
+  y: number;
+  absoluteX: number;
+  absoluteY: number;
+  translationX: number;
+  translationY: number;
+  velocityX: number;
+  velocityY: number;
+};
+
+/**
+ * copy from Reanimated to avoid strong dependency
+ */
+export type GoBackGesture =
+  | 'swipeRight'
+  | 'swipeLeft'
+  | 'swipeUp'
+  | 'swipeDown'
+  | 'verticalSwipe'
+  | 'horizontalSwipe'
+  | 'twoDimensionalSwipe';
+
+export interface MeasuredDimensions {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  pageX: number;
+  pageY: number;
+}
+
+export type AnimatedScreenTransition = {
+  topScreenStyle: (
+    event: PanGestureHandlerEventPayload,
+    screenSize: MeasuredDimensions,
+  ) => Record<string, unknown>;
+  belowTopScreenStyle: (
+    event: PanGestureHandlerEventPayload,
+    screenSize: MeasuredDimensions,
+  ) => Record<string, unknown>;
+};
+
+export type ScreensRefsHolder = Record<string, React.RefObject<View>>;
+
+export interface GestureProps {
+  screensRefs?: React.MutableRefObject<ScreensRefsHolder>;
+  currentScreenId?: string;
+  goBackGesture?: GoBackGesture;
+  transitionAnimation?: AnimatedScreenTransition;
+  screenEdgeGesture?: boolean;
+}
+
+export interface GestureProviderProps extends GestureProps {
+  children?: React.ReactNode;
+  gestureDetectorBridge: React.MutableRefObject<GestureDetectorBridge>;
+}

package/src/useTransitionProgress.tsx

@@ -7,7 +7,7 @@ export default function useTransitionProgress() {
 
   if (progress === undefined) {
     throw new Error(
-      "Couldn't find values for transition progress. Are you inside a screen in Native Stack?"
+      "Couldn't find values for transition progress. Are you inside a screen in Native Stack?",
     );
   }
 

package/src/utils.ts

@@ -11,8 +11,30 @@ export function executeNativeBackPress() {
   return true;
 }
 
-// Because of a bug introduced in https://github.com/software-mansion/react-native-screens/pull/1646
-// react-native-screens v3.21 changed how header's backTitle handles whitespace strings in https://github.com/software-mansion/react-native-screens/pull/1726
-// To allow for backwards compatibility in @react-navigation/native-stack we need a way to check if this version or newer is used.
-// See https://github.com/react-navigation/react-navigation/pull/11423 for more context.
-export const isNewBackTitleImplementation = true;
+/**
+ * Exposes information useful for downstream navigation library implementers,
+ * so they can keep reasonable backward compatibility, if desired.
+ *
+ * We don't mean for this object to only grow in number of fields, however at the same time
+ * we won't be very hasty to reduce it. Expect gradual changes.
+ */
+export const compatibilityFlags = {
+  /**
+   * Because of a bug introduced in https://github.com/software-mansion/react-native-screens/pull/1646
+   * react-native-screens v3.21 changed how header's backTitle handles whitespace strings in https://github.com/software-mansion/react-native-screens/pull/1726
+   * To allow for backwards compatibility in @react-navigation/native-stack we need a way to check if this version or newer is used.
+   * See https://github.com/react-navigation/react-navigation/pull/11423 for more context.
+   */
+  isNewBackTitleImplementation: true,
+
+  /**
+   * With version 4.0.0 the header implementation has been changed. To allow for backward compat
+   * with native-stack@v6 we want to expose a way to check whether the new implementation
+   * is in use or not.
+   *
+   * See:
+   * * https://github.com/software-mansion/react-native-screens/pull/2325
+   * * https://github.com/react-navigation/react-navigation/pull/12125
+   */
+  usesHeaderFlexboxImplementation: true,
+};

package/windows/README.md

@@ -1,12 +1,15 @@
 # react-native-screens Windows Implementation
 
 ## Module Installation
+
 You can either use autolinking on react-native-windows 0.63 and later or manually link the module on earlier releases.
 
 ## Automatic install with autolinking on RNW >= 0.63
+
 RNScreens supports autolinking. Just call: `npm i react-native-screens --save`
 
 ## Manual installation on RNW >= 0.62
+
 1. `npm install react-native-screens --save`
 2. Open your solution in Visual Studio 2019 (eg. `windows\yourapp.sln`)
 3. Right-click Solution icon in Solution Explorer > Add > Existing Project...
@@ -22,4 +25,4 @@ If you want to contribute to this module Windows implementation, first you must
 
 You must temporarily install the `react-native-windows` package. Versions of `react-native-windows` and `react-native` must match, e.g. if the module uses `react-native@0.62`, install `npm i react-native-windows@^0.62 --dev`.
 
-Now, you will be able to open corresponding `RNScreens...sln` file, e.g. `RNScreens62.sln` for `react-native-windows@0.62`.
+Now, you will be able to open corresponding `RNScreens...sln` file, e.g. `RNScreens62.sln` for `react-native-windows@0.62`.

package/windows/RNScreens/Screen.h

@@ -10,7 +10,9 @@ enum class StackAnimation {
   FADE,
   SIMPLE_FROM_BOTTOM,
   SLIDE_FROM_RIGHT,
-  SLIDE_FROM_LEFT
+  SLIDE_FROM_LEFT,
+  IOS_FROM_RIGHT,
+  IOS_FROM_LEFT
 };
 
 enum class ReplaceAnimation { PUSH, POP };