chore(examples): allow to set route options in StackContainer (#3625)

## Description

Add `SetRouteOptionsActionMethod` allowing to modify route options.

Closes
<software-mansion/react-native-screens-labs#936>

It only modifies options of the particular `StackRoute` indicated
by the passed `routeKey`.
Route configuration is an input to the `StackContainer` & it shouldn't
be changed from `StackContainer`. This is sometimes useful however, but
it should be introduced separately.

## Changes

I've added this to `StackContainer` "navigation methods". It does not
fit well to the naming,
but I think that code requires a bit of cleanup / refactor anyway.

## Visual documentation


https://github.com/user-attachments/assets/babb79f0-f479-4f02-bb5a-5658c46edb4e

## Test plan

I've added option to dynamically configure `preventNativeDismiss` in
`prevent-native-dismiss-single-stack`
& `prevent-native-dismiss-nested-stack`. This has been missing from that
tests.

## Checklist

- [x] Included code example that can be used to test this change.
- [x] Updated / created local changelog entries in relevant test files.
- [x] For visual changes, included screenshots / GIFs / recordings
documenting the change.
- [x] For API changes, updated relevant public types.
- [x] Ensured that CI passes

Author: kkafar

apps/src/shared/gamma/containers/stack/StackContainer.tsx

@@ -69,6 +69,7 @@ export function StackContainer({ routeConfigs }: StackContainerProps) {
             pop: navMethods.popAction,
             preload: navMethods.preloadAction,
             batch: navMethods.batchAction,
+            setRouteOptions: navMethods.setRouteOptions,
           };
 
           return (

apps/src/shared/gamma/containers/stack/StackContainer.types.tsx

@@ -8,6 +8,9 @@ export type StackRouteOptions = Omit<
   'children' | 'activityMode' | 'screenKey'
 >;
 
+/**
+ * Blueprint for a route.
+ */
 export type StackRouteConfig = {
   name: string;
   Component: React.ComponentType;
@@ -31,6 +34,10 @@ export type PopCompletedActionMethod = (routeKey: string) => void;
 export type PopNativeActionMethod = (routeKey: string) => void;
 export type PreloadActionMethod = (routeName: string) => void;
 export type BatchActionMethod = (actions: BatchableNavigationAction[]) => void;
+export type SetRouteOptionsActionMethod = (
+  routeKey: string,
+  options: Partial<StackRouteOptions>,
+) => void;
 export type ClearEffectsActionMethod = () => void;
 
 export type NavigationActionMethods = {
@@ -41,6 +48,12 @@ export type NavigationActionMethods = {
   preloadAction: PreloadActionMethod;
   batchAction: BatchActionMethod;
   clearEffectsAction: ClearEffectsActionMethod;
+  /**
+   * Change options for the current route. This does not modify a blueprint
+   * (StackRouteConfig) for the route. It only modifies options for the
+   * given route instance.
+   */
+  setRouteOptions: SetRouteOptionsActionMethod;
 };
 
 export type StackState = StackRoute[];
@@ -98,14 +111,22 @@ export type NavigationActionClearEffects = {
   ctx: NavigationActionContext;
 };
 
+export type NavigationActionSetRouteOptions = {
+  type: 'set-options';
+  routeKey: string;
+  options: Partial<StackRouteOptions>;
+  ctx: NavigationActionContext;
+};
+
 export type NavigationActionContext = {
   routeConfigs: StackRouteConfig[];
 };
 
 export type BatchableNavigationAction =
   | Omit<NavigationActionPush, 'ctx'>
   | Omit<NavigationActionPop, 'ctx'>
-  | Omit<NavigationActionPreload, 'ctx'>;
+  | Omit<NavigationActionPreload, 'ctx'>
+  | Omit<NavigationActionSetRouteOptions, 'ctx'>;
 
 export type NavigationAction =
   | NavigationActionPush
@@ -114,4 +135,5 @@ export type NavigationAction =
   | NavigationActionNativePop
   | NavigationActionPreload
   | NavigationActionClearEffects
+  | NavigationActionSetRouteOptions
   | NavigationActionBatch;

apps/src/shared/gamma/containers/stack/contexts/StackNavigationContext.tsx

@@ -4,6 +4,7 @@ import type {
   PopActionMethod,
   PreloadActionMethod,
   PushActionMethod,
+  SetRouteOptionsActionMethod,
   StackRouteOptions,
 } from '../StackContainer.types';
 
@@ -14,6 +15,7 @@ export type StackNavigationContextPayload = {
   pop: PopActionMethod;
   preload: PreloadActionMethod;
   batch: BatchActionMethod;
+  setRouteOptions: SetRouteOptionsActionMethod;
 };
 
 export const StackNavigationContext =

apps/src/shared/gamma/containers/stack/hooks/useStackOperationMethods.tsx

@@ -11,7 +11,9 @@ import {
   PopNativeActionMethod,
   PreloadActionMethod,
   PushActionMethod,
+  SetRouteOptionsActionMethod as SetRouteOptionsActionMethod,
   StackRouteConfig,
+  StackRouteOptions,
 } from '../StackContainer.types';
 
 export function useStackOperationMethods(
@@ -79,6 +81,13 @@ export function useStackOperationMethods(
     dispatch({ type: 'clear-effects', ctx: actionContext });
   }, [dispatch, actionContext]);
 
+  const setRouteOptions: SetRouteOptionsActionMethod = React.useCallback(
+    (routeKey: string, options: Partial<StackRouteOptions>) => {
+      dispatch({ type: 'set-options', routeKey, options, ctx: actionContext });
+    },
+    [dispatch, actionContext],
+  );
+
   const aggregateValue = React.useMemo(() => {
     return {
       pushAction,
@@ -88,6 +97,7 @@ export function useStackOperationMethods(
       preloadAction,
       batchAction,
       clearEffectsAction,
+      setRouteOptions,
     };
   }, [
     pushAction,
@@ -97,6 +107,7 @@ export function useStackOperationMethods(
     preloadAction,
     batchAction,
     clearEffectsAction,
+    setRouteOptions,
   ]);
 
   return aggregateValue;

apps/src/shared/gamma/containers/stack/reducer.tsx

@@ -8,6 +8,7 @@ import type {
   NavigationActionPopCompleted,
   NavigationActionPreload,
   NavigationActionPush,
+  NavigationActionSetRouteOptions,
   StackNavigationEffect,
   StackNavigationState,
   StackRoute,
@@ -44,6 +45,9 @@ export function navigationStateReducer(
     case 'clear-effects': {
       return navigationActionClearEffectsHandler(state, action);
     }
+    case 'set-options': {
+      return navigationActionSetOptionsHandler(state, action);
+    }
   }
 
   // @ts-ignore
@@ -87,7 +91,7 @@ function navigationActionPushHandler(
     const newStack = stack.toSpliced(renderedRouteIndex, 1);
     const routeCopy = { ...route };
     routeCopy.activityMode = 'attached';
-    return stackNavStateWithStack(state, applyPush(newStack, routeCopy));
+    return stateWithStack(state, applyPush(newStack, routeCopy));
   }
 
   // 2 - Try to render new route
@@ -101,7 +105,7 @@ function navigationActionPushHandler(
   }
 
   const newRoute = createRouteFromConfig(newRouteConfig, 'attached');
-  return stackNavStateWithStack(state, applyPush(state.stack, newRoute));
+  return stateWithStack(state, applyPush(state.stack, newRoute));
 }
 
 function navigationActionPopHandler(
@@ -132,7 +136,7 @@ function navigationActionPopHandler(
       // If there is already a pop-container effect, do nothing
       return state;
     }
-    return stackNavStateWithEffects(
+    return stateWithEffects(
       state,
       applyEffect(state.effects, { type: 'pop-container' }),
     );
@@ -164,7 +168,7 @@ function navigationActionPopHandler(
   // and the original state won't be immediatelly affected.
   route.activityMode = 'detached';
 
-  return stackNavStateWithStack(state, newStack);
+  return stateWithStack(state, newStack);
 }
 
 function navigationActionPopCompletedHandler(
@@ -192,7 +196,7 @@ function navigationActionPopCompletedHandler(
   // Let's remove the route from the state
   // TODO: Consider adding option for keeping it in state.
   const newStack = stack.toSpliced(routeIndex, 1);
-  return stackNavStateWithStack(state, newStack);
+  return stateWithStack(state, newStack);
 }
 
 function navigationActionNativePopHandler(
@@ -222,7 +226,7 @@ function navigationActionNativePopHandler(
   }
 
   const newStack = stack.toSpliced(routeIndex, 1);
-  return stackNavStateWithStack(state, newStack);
+  return stateWithStack(state, newStack);
 }
 
 function navigationActionPreloadHandler(
@@ -244,7 +248,7 @@ function navigationActionPreloadHandler(
   // that won't result in problems on native platform.
   // More info: https://github.com/software-mansion/react-native-screens/pull/3531.
   const newStack = [...state.stack, createRouteFromConfig(routeConfig)];
-  return stackNavStateWithStack(state, newStack);
+  return stateWithStack(state, newStack);
 }
 
 function navigationActionBatchHandler(
@@ -272,7 +276,33 @@ function navigationActionClearEffectsHandler(
   if (state.effects.length === 0) {
     return state;
   }
-  return stackNavStateWithEffects(state, []);
+  return stateWithEffects(state, []);
+}
+
+function navigationActionSetOptionsHandler(
+  state: StackNavigationState,
+  action: NavigationActionSetRouteOptions,
+): StackNavigationState {
+  const routeIndex = state.stack.findIndex(
+    route => route.routeKey === action.routeKey,
+  );
+
+  if (routeIndex === NOT_FOUND_INDEX) {
+    throw new Error(
+      `[Stack] Can not set options. Route with key ${action.routeKey} not found`,
+    );
+  }
+
+  const routeCopy = { ...state.stack[routeIndex] };
+  routeCopy.options = {
+    ...routeCopy.options,
+    ...action.options,
+  };
+
+  return stateWithStack(
+    state,
+    stackWithReplacedRoute(state.stack, routeCopy, routeIndex),
+  );
 }
 
 // Ensures correct order of screens (attached first, detached at the end).
@@ -312,7 +342,7 @@ function generateRouteKeyForRouteName(routeName: string): string {
   return `r-${routeName}-${generateID()}`;
 }
 
-function stackNavStateWithStack(
+function stateWithStack(
   navState: StackNavigationState,
   newStack: StackState,
 ): StackNavigationState {
@@ -322,7 +352,7 @@ function stackNavStateWithStack(
   };
 }
 
-function stackNavStateWithEffects(
+function stateWithEffects(
   navState: StackNavigationState,
   newEffects: StackNavigationEffect[],
 ): StackNavigationState {
@@ -331,3 +361,11 @@ function stackNavStateWithEffects(
     effects: newEffects,
   };
 }
+
+function stackWithReplacedRoute(
+  state: StackState,
+  newRoute: StackRoute,
+  routeIndex: number,
+): StackState {
+  return state.toSpliced(routeIndex, 1, newRoute);
+}

apps/src/tests/single-feature-tests/stack-v5/prevent-native-dismiss-nested-stack.tsx

@@ -89,6 +89,7 @@ function AScreen() {
       <RouteInformation routeName="A" />
       <PreventNativeDismissInfo />
       <NavigationButtons isPopEnabled routeNames={['A', 'B', 'NestedStack']} />
+      <TogglePreventNativeDismiss />
     </CenteredLayoutView>
   );
 }
@@ -99,6 +100,7 @@ function BScreen() {
       <RouteInformation routeName="B" />
       <PreventNativeDismissInfo />
       <NavigationButtons isPopEnabled routeNames={['A', 'B', 'NestedStack']} />
+      <TogglePreventNativeDismiss />
     </CenteredLayoutView>
   );
 }
@@ -154,6 +156,7 @@ function NestedHomeScreen() {
       <RouteInformation routeName="NestedHome" />
       <PreventNativeDismissInfo />
       <NavigationButtons isPopEnabled routeNames={['NestedA', 'NestedB']} />
+      <TogglePreventNativeDismiss />
     </CenteredLayoutView>
   );
 }
@@ -164,6 +167,7 @@ function NestedAScreen() {
       <RouteInformation routeName="NestedA" />
       <PreventNativeDismissInfo />
       <NavigationButtons isPopEnabled routeNames={['NestedA', 'NestedB']} />
+      <TogglePreventNativeDismiss />
     </CenteredLayoutView>
   );
 }
@@ -174,6 +178,7 @@ function NestedBScreen() {
       <RouteInformation routeName="NestedB" />
       <PreventNativeDismissInfo />
       <NavigationButtons isPopEnabled routeNames={['NestedA', 'NestedB']} />
+      <TogglePreventNativeDismiss />
     </CenteredLayoutView>
   );
 }
@@ -214,6 +219,21 @@ function NavigationButtons(props: {
   );
 }
 
+function TogglePreventNativeDismiss() {
+  const navigation = useStackNavigationContext();
+
+  return (
+    <Button
+      title="Toggle Prevent Native Dismiss"
+      onPress={() =>
+        navigation.setRouteOptions(navigation.routeKey, {
+          preventNativeDismiss: !navigation.routeOptions.preventNativeDismiss,
+        })
+      }
+    />
+  );
+}
+
 function PreventNativeDismissInfo() {
   const navContext = useStackNavigationContext();
 

apps/src/tests/single-feature-tests/stack-v5/prevent-native-dismiss-single-stack.tsx

@@ -78,6 +78,7 @@ function AScreen() {
       <RouteInformation routeName="A" />
       <PreventNativeDismissInfo />
       <NavigationButtons isPopEnabled={true} />
+      <TogglePreventNativeDismiss />
     </CenteredLayoutView>
   );
 }
@@ -88,6 +89,7 @@ function BScreen() {
       <RouteInformation routeName="B" />
       <PreventNativeDismissInfo />
       <NavigationButtons isPopEnabled={true} />
+      <TogglePreventNativeDismiss />
     </CenteredLayoutView>
   );
 }
@@ -120,6 +122,21 @@ function NavigationButtons(props: { isPopEnabled: boolean }) {
   );
 }
 
+function TogglePreventNativeDismiss() {
+  const navigation = useStackNavigationContext();
+
+  return (
+    <Button
+      title="Toggle Prevent Native Dismiss"
+      onPress={() =>
+        navigation.setRouteOptions(navigation.routeKey, {
+          preventNativeDismiss: !navigation.routeOptions.preventNativeDismiss,
+        })
+      }
+    />
+  );
+}
+
 function PreventNativeDismissInfo() {
   const navContext = useStackNavigationContext();