@amazon-devices/react-navigation__stack 7.0.1758683737 → 8.0.9000000000

package/src/types.tsx

@@ -1,12 +1,14 @@
 import type {
   HeaderBackButton,
+  HeaderBackButtonDisplayMode,
   HeaderBackButtonProps,
-  HeaderButtonProps,
   HeaderOptions,
   HeaderTitleProps,
 } from '@amazon-devices/react-navigation__elements';
 import type {
+  DefaultNavigatorOptions,
   Descriptor,
+  LocaleDirection,
   NavigationHelpers,
   NavigationProp,
   ParamListBase,
@@ -14,6 +16,8 @@ import type {
   RouteProp,
   StackActionHelpers,
   StackNavigationState,
+  StackRouterOptions,
+  Theme,
 } from '@amazon-devices/react-navigation__native';
 import type * as React from 'react';
 import type { Animated, StyleProp, TextStyle, ViewStyle } from 'react-native';
@@ -50,7 +54,7 @@ export type StackNavigationHelpers = NavigationHelpers<
 export type StackNavigationProp<
   ParamList extends ParamListBase,
   RouteName extends keyof ParamList = keyof ParamList,
-  NavigatorID extends string | undefined = undefined
+  NavigatorID extends string | undefined = undefined,
 > = NavigationProp<
   ParamList,
   RouteName,
@@ -64,12 +68,20 @@ export type StackNavigationProp<
 export type StackScreenProps<
   ParamList extends ParamListBase,
   RouteName extends keyof ParamList = keyof ParamList,
-  NavigatorID extends string | undefined = undefined
+  NavigatorID extends string | undefined = undefined,
 > = {
   navigation: StackNavigationProp<ParamList, RouteName, NavigatorID>;
   route: RouteProp<ParamList, RouteName>;
 };
 
+export type StackOptionsArgs<
+  ParamList extends ParamListBase,
+  RouteName extends keyof ParamList = keyof ParamList,
+  NavigatorID extends string | undefined = undefined,
+> = StackScreenProps<ParamList, RouteName, NavigatorID> & {
+  theme: Theme;
+};
+
 export type Layout = { width: number; height: number };
 
 export type GestureDirection =
@@ -78,8 +90,20 @@ export type GestureDirection =
   | 'vertical'
   | 'vertical-inverted';
 
+export type StackAnimationName =
+  | 'default'
+  | 'fade'
+  | 'fade_from_bottom'
+  | 'fade_from_right'
+  | 'none'
+  | 'reveal_from_bottom'
+  | 'scale_from_center'
+  | 'slide_from_bottom'
+  | 'slide_from_right'
+  | 'slide_from_left';
+
 type SceneOptionsDefaults = TransitionPreset & {
-  animationEnabled: boolean;
+  animation: StackAnimationName;
   gestureEnabled: boolean;
   cardOverlayEnabled: boolean;
   headerMode: StackHeaderMode;
@@ -139,11 +163,11 @@ export type StackHeaderOptions = Omit<
   /**
    * Function which returns a React Element to display on the left side of the header.
    */
-  headerLeft?: (props: HeaderBackButtonProps) => React.ReactNode;
+  headerLeft?: (props: StackHeaderLeftProps) => React.ReactNode;
   /**
    * Function which returns a React Element to display on the right side of the header.
    */
-  headerRight?: (props: HeaderButtonProps) => React.ReactNode;
+  headerRight?: (props: StackHeaderRightProps) => React.ReactNode;
   /**
    * Whether back button title font should scale to respect Text Size accessibility settings. Defaults to `false`.
    */
@@ -159,23 +183,31 @@ export type StackHeaderOptions = Omit<
   /**
    * Title string used by the back button on iOS.
    * Defaults to the previous screen's title, or "Back" if there's not enough space.
-   * Use `headerBackTitleVisible: false` to hide it.
+   * Use `headerBackButtonDisplayMode` to customize the behavior.
    */
   headerBackTitle?: string;
   /**
-   * Whether the back button title should be visible or not.
+   * Title string used by the back button when `headerBackTitle` doesn't fit on the screen.
+   * Use `headerBackButtonDisplayMode` to customize the behavior.
    *
-   * Defaults to `true` on iOS, `false` on Android.
+   * Defaults to "Back".
    */
-  headerBackTitleVisible?: boolean;
+  headerBackTruncatedTitle?: string;
   /**
-   * Style object for the back title.
+   * How the back button displays icon and title.
+   *
+   * Supported values:
+   * - "default" - Displays one of the following depending on the available space: previous screen's title, truncated title (e.g. 'Back') or no title (only icon).
+   * - "generic" – Displays one of the following depending on the available space: truncated title (e.g. 'Back') or no title (only icon).
+   * - "minimal" – Always displays only the icon without a title.
+   *
+   * Defaults to "default" on iOS, and "minimal" on other platforms.
    */
-  headerBackTitleStyle?: StyleProp<TextStyle>;
+  headerBackButtonDisplayMode?: HeaderBackButtonDisplayMode;
   /**
-   * Title string used by the back button when `headerBackTitle` doesn't fit on the screen. `"Back"` by default.
+   * Style object for the back title.
    */
-  headerTruncatedBackTitle?: string;
+  headerBackTitleStyle?: StyleProp<TextStyle>;
   /**
    * Function which returns a React Element to display custom image in header's back button.
    * It receives the `tintColor` in in the options object as an argument. object.
@@ -196,7 +228,11 @@ export type StackHeaderProps = {
     /**
      * Title of the previous screen.
      */
-    title: string;
+    title: string | undefined;
+    /**
+     * The `href` to use for the anchor tag on web
+     */
+    href: string | undefined;
   };
   /**
    * Animated nodes representing the progress of the animation.
@@ -220,6 +256,32 @@ export type StackHeaderProps = {
   styleInterpolator: StackHeaderStyleInterpolator;
 };
 
+export type StackHeaderRightProps = {
+  /**
+   * Tint color for the header button.
+   */
+  tintColor?: string;
+  /**
+   * Color for material ripple (Android >= 5.0 only).
+   */
+  pressColor?: string;
+  /**
+   * Opacity when the button is pressed, used when ripple is not supported.
+   */
+  pressOpacity?: number;
+  /**
+   * Whether it's possible to navigate back in stack.
+   */
+  canGoBack?: boolean;
+};
+
+export type StackHeaderLeftProps = HeaderBackButtonProps & {
+  /**
+   * Whether it's possible to navigate back in stack.
+   */
+  canGoBack?: boolean;
+};
+
 export type StackDescriptor = Descriptor<
   StackNavigationOptions,
   StackNavigationProp<ParamListBase>,
@@ -296,11 +358,20 @@ export type StackNavigationOptions = StackHeaderOptions &
      */
     presentation?: 'card' | 'modal' | 'transparentModal';
     /**
-     * Whether transition animation should be enabled the screen.
-     * If you set it to `false`, the screen won't animate when pushing or popping.
-     * Defaults to `true` on Android and iOS, `false` on Web.
+     * How the screen should animate when pushed or popped.
+     *
+     * Supported values:
+     * - 'none': don't animate the screen
+     * - 'default': use the platform default animation
+     * - 'fade': fade screen in or out
+     * - 'fade_from_bottom': fade screen in or out from bottom
+     * - 'slide_from_bottom': slide in the new screen from bottom
+     * - 'slide_from_right': slide in the new screen from right
+     * - 'slide_from_left': slide in the new screen from left
+     * - 'reveal_from_bottom': reveal screen in from bottom to top
+     * - 'scale_from_center': scale screen in from center
      */
-    animationEnabled?: boolean;
+    animation?: StackAnimationName;
     /**
      * The type of animation to use when this screen replaces another screen. Defaults to `push`.
      * When `pop` is used, the `pop` animation is applied to the screen being replaced.
@@ -341,6 +412,12 @@ export type StackNavigationOptions = StackHeaderOptions &
      * Only supported on iOS and Android.
      */
     freezeOnBlur?: boolean;
+    /**
+     * Whether the home indicator should prefer to stay hidden on this screen. Defaults to `false`.
+     *
+     * @platform ios
+     */
+    autoHideHomeIndicator?: boolean;
   };
 
 export type StackNavigationConfig = {
@@ -404,7 +481,7 @@ export type StackCardInterpolationProps = {
   /**
    * Animated node representing multiplier when direction is inverted (-1 - inverted, 1 - normal).
    */
-  inverted: Animated.AnimatedInterpolation<-1 | 1>;
+  inverted: Animated.AnimatedInterpolation<1 | -1>;
   /**
    * Layout measurements for various items we use for animation.
    */
@@ -429,19 +506,19 @@ export type StackCardInterpolatedStyle = {
   /**
    * Interpolated style for the container view wrapping the card.
    */
-  containerStyle?: any;
+  containerStyle?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
   /**
    * Interpolated style for the view representing the card.
    */
-  cardStyle?: any;
+  cardStyle?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
   /**
    * Interpolated style for the view representing the semi-transparent overlay below the card.
    */
-  overlayStyle?: any;
+  overlayStyle?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
   /**
    * Interpolated style representing the card shadow.
    */
-  shadowStyle?: any;
+  shadowStyle?: Animated.WithAnimatedValue<StyleProp<ViewStyle>>;
 };
 
 export type StackCardStyleInterpolator = (
@@ -468,6 +545,10 @@ export type StackHeaderInterpolationProps = {
      */
     progress: Animated.AnimatedInterpolation<number>;
   };
+  /**
+   * Writing direction of the layout.
+   */
+  direction: LocaleDirection;
   /**
    * Layout measurements for various items we use for animation.
    */
@@ -545,3 +626,14 @@ export type TransitionPreset = {
    */
   headerStyleInterpolator: StackHeaderStyleInterpolator;
 };
+
+export type StackNavigatorProps = DefaultNavigatorOptions<
+  ParamListBase,
+  string | undefined,
+  StackNavigationState<ParamListBase>,
+  StackNavigationOptions,
+  StackNavigationEventMap,
+  StackNavigationProp<ParamListBase>
+> &
+  StackRouterOptions &
+  StackNavigationConfig;

package/src/utils/CardAnimationContext.tsx

@@ -2,6 +2,6 @@ import * as React from 'react';
 
 import type { StackCardInterpolationProps } from '../types';
 
-export default React.createContext<StackCardInterpolationProps | undefined>(
-  undefined
-);
+export const CardAnimationContext = React.createContext<
+  StackCardInterpolationProps | undefined
+>(undefined);

package/src/utils/GestureHandlerRefContext.tsx

@@ -1,5 +1,5 @@
 import * as React from 'react';
 
-export default React.createContext<React.Ref<
-  import('react-native-gesture-handler').PanGestureHandler
+export const GestureHandlerRefContext = React.createContext<React.Ref<
+  import('@amazon-devices/react-native-gesture-handler').PanGestureHandler
 > | null>(null);

package/src/utils/ModalPresentationContext.tsx

@@ -1,5 +1,3 @@
 import * as React from 'react';
 
-const ModalPresentationContext = React.createContext(false);
-
-export default ModalPresentationContext;
+export const ModalPresentationContext = React.createContext(false);

package/src/utils/conditional.tsx

@@ -9,7 +9,7 @@ const { add, multiply } = Animated;
  * @param main Animated Node to use if the condition is `true`
  * @param fallback Animated Node to use if the condition is `false`
  */
-export default function conditional(
+export function conditional(
   condition: Animated.AnimatedInterpolation<0 | 1>,
   main: Animated.AnimatedInterpolation<number>,
   fallback: Animated.AnimatedInterpolation<number>

package/src/utils/findLastIndex.tsx

@@ -1,8 +1,5 @@
-export default function findLastIndex<T>(
-  array: T[],
-  callback: (value: T) => boolean
-) {
-  for (var i = array.length - 1; i >= 0; i--) {
+export function findLastIndex<T>(array: T[], callback: (value: T) => boolean) {
+  for (let i = array.length - 1; i >= 0; i--) {
     if (callback(array[i])) {
       return i;
     }

package/src/utils/gestureActivationCriteria.tsx

@@ -0,0 +1,70 @@
+import type { LocaleDirection } from '@amazon-devices/react-navigation__native';
+
+import type { GestureDirection, Layout } from '../types';
+import { getInvertedMultiplier } from './getInvertedMultiplier';
+
+/**
+ * The distance of touch start from the edge of the screen where the gesture will be recognized
+ */
+const GESTURE_RESPONSE_DISTANCE_HORIZONTAL = 50;
+const GESTURE_RESPONSE_DISTANCE_VERTICAL = 135;
+
+export const gestureActivationCriteria = ({
+  direction,
+  gestureDirection,
+  gestureResponseDistance,
+  layout,
+}: {
+  direction: LocaleDirection;
+  gestureDirection: GestureDirection;
+  gestureResponseDistance?: number;
+  layout: Layout;
+}) => {
+  const enableTrackpadTwoFingerGesture = true;
+
+  const distance =
+    gestureResponseDistance !== undefined
+      ? gestureResponseDistance
+      : gestureDirection === 'vertical' ||
+          gestureDirection === 'vertical-inverted'
+        ? GESTURE_RESPONSE_DISTANCE_VERTICAL
+        : GESTURE_RESPONSE_DISTANCE_HORIZONTAL;
+
+  if (gestureDirection === 'vertical') {
+    return {
+      maxDeltaX: 15,
+      minOffsetY: 5,
+      hitSlop: { bottom: -layout.height + distance },
+      enableTrackpadTwoFingerGesture,
+    };
+  } else if (gestureDirection === 'vertical-inverted') {
+    return {
+      maxDeltaX: 15,
+      minOffsetY: -5,
+      hitSlop: { top: -layout.height + distance },
+      enableTrackpadTwoFingerGesture,
+    };
+  } else {
+    const hitSlop = -layout.width + distance;
+    const invertedMultiplier = getInvertedMultiplier(
+      gestureDirection,
+      direction === 'rtl'
+    );
+
+    if (invertedMultiplier === 1) {
+      return {
+        minOffsetX: 5,
+        maxDeltaY: 20,
+        hitSlop: { right: hitSlop },
+        enableTrackpadTwoFingerGesture,
+      };
+    } else {
+      return {
+        minOffsetX: -5,
+        maxDeltaY: 20,
+        hitSlop: { left: hitSlop },
+        enableTrackpadTwoFingerGesture,
+      };
+    }
+  }
+};

package/src/utils/getDistanceForDirection.tsx

@@ -1,11 +1,12 @@
 import type { GestureDirection, Layout } from '../types';
-import getInvertedMultiplier from './getInvertedMultiplier';
+import { getInvertedMultiplier } from './getInvertedMultiplier';
 
-export default function getDistanceForDirection(
+export function getDistanceForDirection(
   layout: Layout,
-  gestureDirection: GestureDirection
+  gestureDirection: GestureDirection,
+  isRTL: boolean
 ): number {
-  const multiplier = getInvertedMultiplier(gestureDirection);
+  const multiplier = getInvertedMultiplier(gestureDirection, isRTL);
 
   switch (gestureDirection) {
     case 'vertical':

package/src/utils/getInvertedMultiplier.tsx

@@ -1,9 +1,8 @@
-import { I18nManager } from 'react-native';
-
 import type { GestureDirection } from '../types';
 
-export default function getInvertedMultiplier(
-  gestureDirection: GestureDirection
+export function getInvertedMultiplier(
+  gestureDirection: GestureDirection,
+  isRTL: boolean
 ): 1 | -1 {
   switch (gestureDirection) {
     case 'vertical':
@@ -11,8 +10,8 @@ export default function getInvertedMultiplier(
     case 'vertical-inverted':
       return -1;
     case 'horizontal':
-      return I18nManager.getConstants().isRTL ? -1 : 1;
+      return isRTL ? -1 : 1;
     case 'horizontal-inverted':
-      return I18nManager.getConstants().isRTL ? 1 : -1;
+      return isRTL ? 1 : -1;
   }
 }

package/src/utils/getModalRoutesKeys.ts

@@ -0,0 +1,21 @@
+import type { Route } from '@amazon-devices/react-navigation__native';
+
+import type { StackDescriptorMap } from '../types';
+
+export const getModalRouteKeys = (
+  routes: Route<string>[],
+  descriptors: StackDescriptorMap
+) =>
+  routes.reduce<string[]>((acc, route) => {
+    const { presentation } = descriptors[route.key]?.options ?? {};
+
+    if (
+      (acc.length && !presentation) ||
+      presentation === 'modal' ||
+      presentation === 'transparentModal'
+    ) {
+      acc.push(route.key);
+    }
+
+    return acc;
+  }, []);

package/src/utils/getShadowStyle.tsx

@@ -0,0 +1,37 @@
+import Color from 'color';
+import { Platform } from 'react-native';
+
+type ShadowConfig = {
+  offset: {
+    width: number;
+    height: number;
+  };
+  radius: number;
+  opacity: number;
+  color?: string;
+};
+
+export function getShadowStyle({
+  offset,
+  radius,
+  opacity,
+  color = '#000',
+}: ShadowConfig) {
+  const result = Platform.select({
+    web: {
+      boxShadow: `${offset.width}px ${offset.height}px ${radius}px ${Color(
+        color
+      )
+        .alpha(opacity)
+        .toString()}`,
+    },
+    default: {
+      shadowOffset: offset,
+      shadowRadius: radius,
+      shadowColor: color,
+      shadowOpacity: opacity,
+    },
+  });
+
+  return result;
+}

package/src/utils/throttle.tsx

@@ -0,0 +1,16 @@
+export function throttle<T extends (...args: any[]) => void>(
+  func: T,
+  duration: number
+): T {
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+
+  return function (this: unknown, ...args) {
+    if (timeout == null) {
+      func.apply(this, args);
+
+      timeout = setTimeout(() => {
+        timeout = undefined;
+      }, duration);
+    }
+  } as T;
+}

package/src/utils/useCardAnimation.tsx

@@ -1,8 +1,8 @@
 import * as React from 'react';
 
-import CardAnimationContext from './CardAnimationContext';
+import { CardAnimationContext } from './CardAnimationContext';
 
-export default function useCardAnimation() {
+export function useCardAnimation() {
   const animation = React.useContext(CardAnimationContext);
 
   if (animation === undefined) {

package/src/utils/useGestureHandlerRef.tsx

@@ -1,9 +1,9 @@
 import * as React from 'react';
 
-import StackGestureRefContext from './GestureHandlerRefContext';
+import { GestureHandlerRefContext } from './GestureHandlerRefContext';
 
-export default function useGestureHandlerRef() {
-  const ref = React.useContext(StackGestureRefContext);
+export function useGestureHandlerRef() {
+  const ref = React.useContext(GestureHandlerRefContext);
 
   if (ref === undefined) {
     throw new Error(

package/src/utils/useKeyboardManager.tsx

@@ -1,14 +1,12 @@
 import * as React from 'react';
-import { HostComponent, Keyboard, TextInput } from 'react-native';
+import { type HostInstance, Keyboard, TextInput } from 'react-native';
 
-type InputRef = React.ElementRef<HostComponent<unknown>> | undefined;
-
-export default function useKeyboardManager(isEnabled: () => boolean) {
+export function useKeyboardManager(isEnabled: () => boolean) {
   // Numeric id of the previously focused text input
   // When a gesture didn't change the tab, we can restore the focused input with this
-  const previouslyFocusedTextInputRef = React.useRef<InputRef>(undefined);
+  const previouslyFocusedTextInputRef = React.useRef<HostInstance>(undefined);
   const startTimestampRef = React.useRef<number>(0);
-  const keyboardTimeoutRef = React.useRef<any>();
+  const keyboardTimeoutRef = React.useRef<NodeJS.Timeout>(undefined);
 
   const clearKeyboardTimeout = React.useCallback(() => {
     if (keyboardTimeoutRef.current !== undefined) {
@@ -24,7 +22,7 @@ export default function useKeyboardManager(isEnabled: () => boolean) {
 
     clearKeyboardTimeout();
 
-    const input: InputRef = TextInput.State.currentlyFocusedInput();
+    const input = TextInput.State.currentlyFocusedInput();
 
     // When a page change begins, blur the currently focused input
     input?.blur();

package/src/views/GestureHandler.kepler.tsx

@@ -0,0 +1 @@
+export * from './GestureHandlerNative';

package/src/views/GestureHandler.tsx

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { View } from 'react-native';
-import type { PanGestureHandlerProperties } from 'react-native-gesture-handler';
+import type { PanGestureHandlerProperties } from '@amazon-devices/react-native-gesture-handler';
 
 const Dummy: any = ({ children }: { children: React.ReactNode }) => (
   <>{children}</>
@@ -20,4 +20,4 @@ export const GestureState = {
   END: 5,
 };
 
-export type { PanGestureHandlerGestureEvent } from 'react-native-gesture-handler';
+export type { PanGestureHandlerGestureEvent } from '@amazon-devices/react-native-gesture-handler';

package/src/views/GestureHandlerNative.tsx

@@ -1,10 +1,10 @@
 import * as React from 'react';
 import {
   PanGestureHandler as PanGestureHandlerNative,
-  PanGestureHandlerProperties,
-} from 'react-native-gesture-handler';
+  type PanGestureHandlerProperties,
+} from '@amazon-devices/react-native-gesture-handler';
 
-import GestureHandlerRefContext from '../utils/GestureHandlerRefContext';
+import { GestureHandlerRefContext } from '../utils/GestureHandlerRefContext';
 
 export function PanGestureHandler(props: PanGestureHandlerProperties) {
   const gestureRef = React.useRef<PanGestureHandlerNative>(null);
@@ -16,8 +16,8 @@ export function PanGestureHandler(props: PanGestureHandlerProperties) {
   );
 }
 
-export type { PanGestureHandlerGestureEvent } from 'react-native-gesture-handler';
+export type { PanGestureHandlerGestureEvent } from '@amazon-devices/react-native-gesture-handler';
 export {
   GestureHandlerRootView,
   State as GestureState,
-} from 'react-native-gesture-handler';
+} from '@amazon-devices/react-native-gesture-handler';

package/src/views/Header/Header.tsx

@@ -4,11 +4,11 @@ import * as React from 'react';
 import { useSafeAreaInsets } from '@amazon-devices/react-native-safe-area-context';
 
 import type { StackHeaderProps } from '../../types';
-import debounce from '../../utils/debounce';
-import ModalPresentationContext from '../../utils/ModalPresentationContext';
-import HeaderSegment from './HeaderSegment';
+import { ModalPresentationContext } from '../../utils/ModalPresentationContext';
+import { throttle } from '../../utils/throttle';
+import { HeaderSegment } from './HeaderSegment';
 
-export default React.memo(function Header({
+export const Header = React.memo(function Header({
   back,
   layout,
   progress,
@@ -31,7 +31,7 @@ export default React.memo(function Header({
 
   // eslint-disable-next-line react-hooks/exhaustive-deps
   const goBack = React.useCallback(
-    debounce(() => {
+    throttle(() => {
       if (navigation.isFocused() && navigation.canGoBack()) {
         navigation.dispatch({
           ...StackActions.pop(),
@@ -49,8 +49,8 @@ export default React.memo(function Header({
     options.headerStatusBarHeight !== undefined
       ? options.headerStatusBarHeight
       : isModal || isParentHeaderShown
-      ? 0
-      : insets.top;
+        ? 0
+        : insets.top;
 
   return (
     <HeaderSegment
@@ -66,6 +66,7 @@ export default React.memo(function Header({
       }
       headerStatusBarHeight={statusBarHeight}
       onGoBack={back ? goBack : undefined}
+      backHref={back ? back.href : undefined}
       styleInterpolator={styleInterpolator}
     />
   );