feat(Android, Stack v5): allow for nested container pop via JS (#3612)

## Description
  
Previously it has not been possible to pop nested container via JS.
When there was only a single screen left in the JS stack state, the
reducer would deny removing it and would just ignore the operation
printing a warning that pop operation requires at least two screens.

Currently, in such scenario the parent `StackContainer` (JS component)
will be asked to pop whole screen that hosts the nested container.

## Changes

This is achieved by changes in stack container state reducer.
Previously it operated directly on stack, but now I need to somehow
communicate that an action has not been performed directly on the
container and must be forwarded to parent container. We can
not use the `parentNavigation` directly in the reducer, because:

1. reducer should be pure,
2. we can not dispatch an action directly to the parent container during
render (and this is when the state reducing takes place), React
treats it as an error.

Therefore, I see two possibilities here. Either we move all the
`StackContainer` state to some centralized place (similarly to what
react-navigation does with `NavigationContainer`) or we stay with
current approach (each `StackContainer` owns its state) but we emit
this intent as an side effect.

Right now I went with second option. Reducer, when it find it makes
sense, not only updates the stack state, but also produces side effects
to be performed. Currently, there is only single side effect:
`PopContainerStackNavigationEffect`, but I found it low cost to make it
a bit more generic.

Reducer produces the side effect, which is later consumed by the new
`useParentNavigationEffect` hook.

Important thing to note in this implementation is the referential
stability of the effects array. The state object id changes every time
`state.stack` or `state.effects` change. However, `state.effects` object
id stays the same as long as there is no change to prevent excessive
rendering.

Given a nested stack, with only a single screen in the nested stack,
the flow is as follows:

1. `navigation.pop` is dispatched to the nested stack, this triggers
    render.
2. Reducer detects that it has only a single screen & can not perform
    the action, therefore it produces new state with new effects array
    containing the `PopContainerStackNavigationEffect`.
3. The `useParentNavigationEffect` schedules the `useEffect`, which is
executed after this render.
4. The `useEffect` is executed triggering render of the outer container
and consuming the effect (trigger render of the inner container).
5. New render starts from the outer container -> it performs the
    navigation action, detaching the screen that hosts nested container
6. During the same render as in 5., nested container clears its
    `state.effects`.
7. After the dismiss completes, `pop-completed` operation is dispatched
by event listeners & hosting screen & nested container are cleared from
the state (they no longer render).

> [!note]
> Thing to note here, is that the nested stack's only screen, when it's
> being dismissed it sends `onDismissed(isNativeDismiss=true)` event,
> because it is dismissed & it's activityMode has never been changed to
> `detached`. I don't think this is causing any problems right now,
> but it is definitely something to be aware of.

What happens if there is only a single screen in outer stack & it
hosts the nested stack? Nothing. Renders are triggered, but there is no
one to handle that operation.

## Visual documentation

| before | after | 
| -- | -- | 
| <video
src=https://github.com/user-attachments/assets/836181fb-4f94-488f-93bd-27a58a3e2f20
alt="before" /> | <video
src=https://github.com/user-attachments/assets/84997062-07d6-4a48-878b-08d04e3891be
alt="after" /> |




## Test plan

I'm using `TestStackNesting`.
Just as the video shows.

## 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 (all but Android lint - I'll fix it
separately one day)

Author: kkafar

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

@@ -3,11 +3,11 @@ import { Stack } from 'react-native-screens/experimental';
 import type {
   NavigationAction,
   StackContainerProps,
+  StackNavigationState,
   StackRouteConfig,
-  StackState,
 } from './StackContainer.types';
 import {
-  determineFirstRoute,
+  determineInitialNavigationState,
   navigationStateReducerWithLogging,
 } from './reducer';
 import { useStackOperationMethods } from './hooks/useStackOperationMethods';
@@ -19,21 +19,26 @@ import {
   type NativeComponentGenericRef,
   useRenderDebugInfo,
 } from 'react-native-screens/private';
+import { useParentNavigationEffect } from './hooks/useParentNavigationEffect';
 
 export function StackContainer({ routeConfigs }: StackContainerProps) {
   useSanitizeRouteConfigs(routeConfigs);
 
-  const [stackState, navActionDispatch]: [
-    StackState,
+  const [stackNavState, navActionDispatch]: [
+    StackNavigationState,
     React.Dispatch<NavigationAction>,
   ] = React.useReducer(
     navigationStateReducerWithLogging,
     routeConfigs,
-    determineFirstRoute,
+    determineInitialNavigationState,
   );
 
   const navMethods = useStackOperationMethods(navActionDispatch, routeConfigs);
 
+  // If reducer produced a parent action, we need to dispatch it
+  // as an effect, because we can not modify the state during the render phase.
+  useParentNavigationEffect(navMethods, stackNavState.effects);
+
   const hostRef =
     useRenderDebugInfo<NativeComponentGenericRef>('StackContainer');
 
@@ -55,29 +60,31 @@ export function StackContainer({ routeConfigs }: StackContainerProps) {
 
   return (
     <Stack.Host ref={hostRef}>
-      {stackState.map(({ Component, options, activityMode, routeKey }) => {
-        const stackNavigationContext: StackNavigationContextPayload = {
-          routeKey,
-          push: navMethods.pushAction,
-          pop: navMethods.popAction,
-          preload: navMethods.preloadAction,
-          batch: navMethods.batchAction,
-        };
+      {stackNavState.stack.map(
+        ({ Component, options, activityMode, routeKey }) => {
+          const stackNavigationContext: StackNavigationContextPayload = {
+            routeKey,
+            push: navMethods.pushAction,
+            pop: navMethods.popAction,
+            preload: navMethods.preloadAction,
+            batch: navMethods.batchAction,
+          };
 
-        return (
-          <Stack.Screen
-            key={routeKey}
-            {...options}
-            activityMode={activityMode}
-            screenKey={routeKey}
-            onDismiss={onScreenDismissed}
-            onNativeDismiss={onScreenNativelyDismissed}>
-            <StackNavigationContext.Provider value={stackNavigationContext}>
-              <Component />
-            </StackNavigationContext.Provider>
-          </Stack.Screen>
-        );
-      })}
+          return (
+            <Stack.Screen
+              key={routeKey}
+              {...options}
+              activityMode={activityMode}
+              screenKey={routeKey}
+              onDismiss={onScreenDismissed}
+              onNativeDismiss={onScreenNativelyDismissed}>
+              <StackNavigationContext.Provider value={stackNavigationContext}>
+                <Component />
+              </StackNavigationContext.Provider>
+            </Stack.Screen>
+          );
+        },
+      )}
     </Stack.Host>
   );
 }

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

@@ -1,6 +1,8 @@
 import React from 'react';
 import { StackScreenProps } from 'react-native-screens/experimental';
 
+/// Route definition
+
 export type StackRouteOptions = Omit<
   StackScreenProps,
   'children' | 'activityMode' | 'screenKey'
@@ -12,21 +14,24 @@ export type StackRouteConfig = {
   options: StackRouteOptions;
 };
 
-export type StackContainerProps = {
-  routeConfigs: StackRouteConfig[];
-};
-
 export type StackRoute = StackRouteConfig & {
   activityMode: StackScreenProps['activityMode'];
   routeKey: StackScreenProps['screenKey'];
 };
 
+/// StackContainer props
+
+export type StackContainerProps = {
+  routeConfigs: StackRouteConfig[];
+};
+
 export type PushActionMethod = (routeName: string) => void;
 export type PopActionMethod = (routeKey: string) => void;
 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 ClearEffectsActionMethod = () => void;
 
 export type NavigationActionMethods = {
   pushAction: PushActionMethod;
@@ -35,10 +40,22 @@ export type NavigationActionMethods = {
   popNativeAction: PopNativeActionMethod;
   preloadAction: PreloadActionMethod;
   batchAction: BatchActionMethod;
+  clearEffectsAction: ClearEffectsActionMethod;
 };
 
 export type StackState = StackRoute[];
 
+export type StackNavigationState = {
+  stack: StackState;
+  effects: StackNavigationEffect[];
+};
+
+export type StackNavigationEffect = PopContainerStackNavigationEffect;
+
+type PopContainerStackNavigationEffect = {
+  type: 'pop-container';
+};
+
 export type NavigationActionPush = {
   type: 'push';
   routeName: string;
@@ -74,6 +91,13 @@ export type NavigationActionBatch = {
   actions: Exclude<NavigationAction, NavigationActionBatch>[];
 };
 
+// TODO: We need to separate navigation actions exposed to user from internal
+// state manipulation done in stack container on the type level.
+export type NavigationActionClearEffects = {
+  type: 'clear-effects';
+  ctx: NavigationActionContext;
+};
+
 export type NavigationActionContext = {
   routeConfigs: StackRouteConfig[];
 };
@@ -89,4 +113,5 @@ export type NavigationAction =
   | NavigationActionPopCompleted
   | NavigationActionNativePop
   | NavigationActionPreload
+  | NavigationActionClearEffects
   | NavigationActionBatch;

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

@@ -0,0 +1,39 @@
+import React from 'react';
+import { StackNavigationContext } from '../contexts/StackNavigationContext';
+import type {
+  NavigationActionMethods,
+  StackNavigationEffect,
+} from '../StackContainer.types';
+
+export function useParentNavigationEffect(
+  navActionMethods: NavigationActionMethods,
+  effects: StackNavigationEffect[] | undefined,
+) {
+  const parentNavigation = React.useContext(StackNavigationContext);
+
+  const consumeEffect = React.useEffectEvent(
+    (effect: StackNavigationEffect) => {
+      if (effect.type !== 'pop-container') {
+        throw new Error(`[Stack] Unrecognized effect type: ${effect.type}`);
+      }
+      if (parentNavigation) {
+        console.log(
+          `[Stack] Delegating pop action to parent container for key ${parentNavigation.routeKey}`,
+        );
+        parentNavigation.pop(parentNavigation.routeKey);
+      }
+    },
+  );
+
+  const clearEffects = React.useEffectEvent(() => {
+    navActionMethods.clearEffectsAction();
+  });
+
+  // We want to trigger this effect only when effects change.
+  React.useEffect(() => {
+    if (effects && effects.length > 0) {
+      effects.forEach(consumeEffect);
+      clearEffects();
+    }
+  }, [effects]);
+}

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

@@ -2,6 +2,7 @@ import React from 'react';
 import {
   BatchableNavigationAction,
   BatchActionMethod,
+  ClearEffectsActionMethod,
   NavigationAction,
   NavigationActionContext,
   NavigationActionMethods,
@@ -74,6 +75,10 @@ export function useStackOperationMethods(
     [dispatch, actionContext],
   );
 
+  const clearEffectsAction: ClearEffectsActionMethod = React.useCallback(() => {
+    dispatch({ type: 'clear-effects', ctx: actionContext });
+  }, [dispatch, actionContext]);
+
   const aggregateValue = React.useMemo(() => {
     return {
       pushAction,
@@ -82,6 +87,7 @@ export function useStackOperationMethods(
       popNativeAction,
       preloadAction,
       batchAction,
+      clearEffectsAction,
     };
   }, [
     pushAction,
@@ -90,6 +96,7 @@ export function useStackOperationMethods(
     popNativeAction,
     preloadAction,
     batchAction,
+    clearEffectsAction,
   ]);
 
   return aggregateValue;