chore: add reference `StackContainer` implementation #3518

kkafar · 2026-01-05T11:07:27Z

Description

This PR introduces JS implementation of StackContainer component. It is not library component, but rather a container implementation that is a example of a possible downstream implementation.
It is required for us to have a referential container implementation to test on.

This is not a complete implementation. It is rather a starting point, providing implementation of basic operations following RFC-0591.

Closes https://github.com/software-mansion/react-native-screens-labs/issues/771

Changes

Rename maxLifecycleState to activityMode
Following naming from RFC-0591.

This commit also does necessary cleanup of no longer used types such as
StackScreenLifecycleState.

RNSConversion-Stack is introduced with a convert function template,
which can be possibly later reused for other components as well.
Make type of children prop of StackHost not key-optional
It does not make sense to not specify children for StackHost.
Reimplement StackContainer
The original implementation is hard for me to follow. Moreover it has
been based upon old operation model based on maxLifecycleState.

New operation model introduced in RFC-0591 requires changes in
implementation of stack operations, therefore I took this opportunity
and reimplemented all of it.

The implementation is not completed yet (nor was the previous one).
It introduces single StackContainer component that should be used
to render the new stack.

While implementing I noticed a couple of problems introduced by
me in RFC-0591. First - there is no easy way to get the navigation state
in the JS layer. This is especially troublesome when implementing pop
operation, as it is not clear what screen to dismiss.

The exact problem lies in fact that in current model we allow for
rendering array of Stack.Screens with some in detached mode.
When already rendered Screen changes its mode to attached,
it becomes a top screen, but it's index in the state array does not
change. Therefore, we can not really tell which screen is on top.

Pop operation is one problem, but another is simply dumping current
navigation state e.g. for telemetry purposes / saving app state
before restart or something. I'm sure there are many use cases for
reading current navigation state.
Add useRenderDebugInfo utility hook
It logs component renders, mount & unmount.
We can generalize / move it common code later.
It seems useful.
Fix action name & move useRenderDebugInfo hook to react-native-screens/private
This hook can be reused easily for different components while debugging.
Seems useful enough to add it to private package.
Add basic support for dismiss in JS example code
Add basic support for dismiss in component code
This is rather a PoC than proper support. There are a couple of issues
with current implementation.
Pass info on activityMode change from StackScreen to StackHost
Before this change, the information has been passed from
RNSStackScreenComponentView to StackController via
StackScreenController. This is not compliant with RFC-0753.

The controllers should not be aware of activity mode changes. The
information should be passed directly to StackHost and there request
to container should be dispatched. This is exactly what this commit
does.
Cleanup in component code
Add navigationStateReducerWithLogging that logs actions & state
This is debug-oriented utility.
Prevent pop action from executing when there is at most one attached screen
Previously I checked only whether there is screen at all. This could
lead to corrupted state in obvious way, where all screens were detached!
Fix import in component code

It does not make sense to not specify children for `StackHost`.

The original implementation is hard for me to follow. Moreover it has been based upon old operation model based on `maxLifecycleState`. New operation model introduced in RFC-0591 requires changes in implementation of stack operations, therefore I took this opportunity and reimplemented all of it. The implementation is not completed yet (nor was the previous one). It introduces single `StackContainer` component that should be used to render the new stack. While implementing I noticed a couple of problems introduced by me in RFC-0591. First - there is no easy way to get the navigation state in the JS layer. This is especially troublesome when implementing `pop` operation, as it is not clear what screen to dismiss. The exact problem lies in fact that in current model we allow for rendering array of `Stack.Screen`s with some in `detached` mode. When already rendered `Screen` changes its mode to `attached`, it becomes a top screen, but it's index in the state array does not change. Therefore, we can not really tell which screen is on top. `Pop` operation is one problem, but another is simply dumping current navigation state e.g. for telemetry purposes / saving app state before restart or something. I'm sure there are many use cases for reading current navigation state.

It logs component renders, mount & unmount. We can generalize / move it common code later. It seems useful.

`react-native-screens/private` This hook can be reused easily for different components while debugging. Seems useful enough to add it to private package.

This is rather a PoC than proper support. There are a couple of issues with current implementation.

Before this change, the information has been passed from `RNSStackScreenComponentView` to `StackController` via `StackScreenController`. This is not compliant with RFC-0753. The controllers should not be aware of activity mode changes. The information should be passed directly to `StackHost` and there request to container should be dispatched. This is exactly what this commit does.

This is debug-oriented utility.

screen Previously I checked only whether there is screen at all. This could lead to corrupted state in obvious way, where all screens were detached!

This is essential functionality that I have to add manually each time I debug something. I think since this is still higihly experimental impelmentation it is fine to have some logging there, especially that it is frequently needed to exam the stack state etc.

Please note that preloaded route is pushed as last element of the `stackState`. This can potentially cause problems with element inspector as from ShadowTree perspective the newly rendered screen is the one on the very top (drawn last), despite the fact that it won't be attached to native container. This is not a new problem. Old stack implementation suffers from the very same one. In the future we might consider disabling gestures on the 'detached' screens (pointer events). This might help to mitigate this issue.

It is not used anywhere in computation.

kkafar

Few implementation notes and directions for future work on this PR.

kkafar · 2026-01-07T18:57:39Z

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

+      routeCopy.activityMode = 'attached';
+      newState.push(routeCopy);


Please note that the route is pushed to the end of the state list here, to prevent issues with stack state restoration & element inspector.

kkafar · 2026-01-07T19:21:09Z

ios/gamma/stack/screen/RNSStackScreenComponentEventEmitter.mm

+- (BOOL)emitOnDismiss
+{
+  if (_reactEventEmitter != nullptr) {
+    _reactEventEmitter->onDismiss({});
+    return YES;
+  } else {
+    RCTLogWarn(@"[RNScreens] Skipped OnDismissed event emission due to nullish emitter");
+    return NO;
+  }
+}
+
+- (BOOL)emitOnNativeDismiss
+{
+  if (_reactEventEmitter != nullptr) {
+    _reactEventEmitter->onNativeDismiss({});
+    return YES;
+  } else {
+    RCTLogWarn(@"[RNScreens] Skipped onNativeDismiss event emission due to nullish emitter");
+    return NO;
+  }
+}


We could consider emitting only a single type of event but with boolean in payload. I think it'll be a better approach.

I'd say two function is very slightly more readable (onDismiss could be made even more descriptive, i.e. onCompleteJSDismiss() )

and if those two diverge in the future, we wouldn't need to refactor

Please see: c840b04

kkafar · 2026-01-07T19:23:30Z

ios/gamma/stack/screen/RNSStackScreenController.swift

+  public override func didMove(toParent parent: UIViewController?) {
+    print("ScreenCtrl [\(self.screen.tag)] didMoveToParent \(String(describing: parent))")
+    super.didMove(toParent: parent)
+
+    if parent == nil {
+      if self.screen.activityMode == .detached {
+        reactEventEmitter.emitOnDismiss()
+      } else {
+        reactEventEmitter.emitOnNativeDismiss()
+      }
+    }
+  }


This is absolutely not a correct implementation.
We need a proper way to distinguish a native dismiss from JS initiated one.

This is just PoC code, rough-and-ready for demonstrative purposes only. We can land it, cause it does its purpose at the moment, but we'll have to improve it 100%.

kkafar · 2026-01-07T19:25:04Z

src/components/gamma/stack/StackHost.types.ts

+  ref?: React.RefObject<
+    (React.Component<NativeProps> & ReactNativeElement) | null


I made this type like that just to make things work (and it still does not work correctly). It seemed that there is something incompatible in types between RefObject to React.Component and HostComponentType (type of any native component). Dunno, needs to be investigated.

kkafar · 2026-01-07T19:27:24Z

src/private/hooks/useRenderDebugInfo.tsx

+import React from 'react';
+import { findNodeHandle, ReactNativeElement } from 'react-native';
+
+export type NativeComponentGenericRef = React.Component & ReactNativeElement;
+
+export function useRenderDebugInfo<RefType extends React.Component>(
+  componentName: string,
+) {
+  const componentRef = React.useRef<RefType>(null);
+  const componentNodeHandle = React.useRef<number>(-1);
+
+  const logMessageEvent = React.useEffectEvent((message: string) => {
+    logMessage(componentName, componentNodeHandle.current, message);
+  });
+
+  React.useEffect(() => {
+    if (componentRef.current != null) {
+      componentNodeHandle.current = findNodeHandle(componentRef.current) ?? -1;
+
+      if (componentNodeHandle.current === -1) {
+        logMessageEvent('failed to find node handle');
+      }
+    }
+
+    logMessageEvent('mounted');
+
+    return () => {
+      logMessageEvent('unmounted');
+    };
+  }, []);
+
+  logMessage(componentName, componentNodeHandle.current, 'rendered');
+
+  return componentRef;
+}
+
+function logMessage(
+  componentName: string,
+  nodeHandle: number,
+  message: string,
+) {
+  console.log(`${componentName} [${nodeHandle}] ${message}`);
+}


Tremendously useful thing for logging & debugging I found myself to write multiple times over and over. This time I decided to clean it a bit & add it, so that we can reuse it.

This clearly needs a doc comment explaining what is a purpose of this hook.

Previous implementation fails in scenario: A -> Aa -> AaB -> and push A again. This is because the search end on first A, which is already rendered and attached, falling through to creation of new route. Now, instead we only for detached screens that wait to be rendered. This is not perfect, because I can imagine use cases where we want detached screen, let's say A-1 to stay detached and push another, let's say A-2, e.g. in case A-1 is used for picture-in-picture. But this is concern of downstream implementation / we can figure it out later. Currently such route should not be preloaded.

kligarski

Looks good, I left some suggestions.

Looks like we still have a problem with JS/native state synchronization. As discussed internally, this is expected for now until we handle it on the native side in another PR but I guess it's worth it to document it here.

Simulator.Screen.Recording.-.iPhone.17.Pro.-.2026-01-13.at.10.40.25.mov

kligarski · 2026-01-13T08:31:17Z

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

+
+export type StackRouteConfig = {
+  name: string;
+  Component: () => React.ReactNode;


Should prop name Component be capitalized? Or should it be component?

I wonder what type should be used here. For example, in BottomTabsContainer we use ComponentType. I'm not sure what the right answer is here.

Ad 1.

This is from react legacy docs but I believe the rule still applies:

Ad 2.

I guess ComponentType is more appropriate here. It allows for class component to be passed, which I guess it not that big of advantage, but rather nice thing is that it correctly types Suspending components that potentially return a Promise<React.ReactNode>.

Okay. We should probably match that convention in BottomTabsContainer then. I created a ticket to do so: https://github.com/software-mansion/react-native-screens-labs/issues/776.

src/components/gamma/stack/StackScreen.tsx

src/private/types.ts

kligarski · 2026-01-13T09:19:57Z

ios/gamma/stack/screen/RNSStackScreenComponentEventEmitter.mm

+- (BOOL)emitOnDismiss
+{
+  if (_reactEventEmitter != nullptr) {
+    _reactEventEmitter->onDismiss({});
+    return YES;
+  } else {
+    RCTLogWarn(@"[RNScreens] Skipped OnDismissed event emission due to nullish emitter");
+    return NO;
+  }
+}
+
+- (BOOL)emitOnNativeDismiss
+{
+  if (_reactEventEmitter != nullptr) {
+    _reactEventEmitter->onNativeDismiss({});
+    return YES;
+  } else {
+    RCTLogWarn(@"[RNScreens] Skipped onNativeDismiss event emission due to nullish emitter");
+    return NO;
+  }
+}


ios/gamma/stack/host/RNSStackHostComponentView.mm

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

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

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

kmichalikk · 2026-01-13T12:18:35Z

ios/gamma/stack/screen/RNSStackScreenComponentEventEmitter.mm

+- (BOOL)emitOnDismiss
+{
+  if (_reactEventEmitter != nullptr) {
+    _reactEventEmitter->onDismiss({});
+    return YES;
+  } else {
+    RCTLogWarn(@"[RNScreens] Skipped OnDismissed event emission due to nullish emitter");
+    return NO;
+  }
+}
+
+- (BOOL)emitOnNativeDismiss
+{
+  if (_reactEventEmitter != nullptr) {
+    _reactEventEmitter->onNativeDismiss({});
+    return YES;
+  } else {
+    RCTLogWarn(@"[RNScreens] Skipped onNativeDismiss event emission due to nullish emitter");
+    return NO;
+  }
+}


I'd say two function is very slightly more readable (onDismiss could be made even more descriptive, i.e. onCompleteJSDismiss() )

and if those two diverge in the future, we wouldn't need to refactor

ios/gamma/stack/screen/RNSStackScreenController.swift

These two are replaced by single `onDismiss` event with a boolean in payload, that allows to still distinguish between these two. I've decided to leave `onNativeDismiss` callback on `StackScreen` React component, because it is handy to use in the `StackContainer` implementation.

This is just a safe guard to catch possibly annoying to debug error. This commit also formats the code. I can not get my editor to save without formatting ^_^

Before it has been done in useEffect, which is fine, but this seems cleaner. This changes behaviour a bit, because earlier when after initial render for some reason the number of routes in state was decreased to 0, the useEffect would ensure that there is at least a single route present. Now this isn't the case. The stack will end up empty. This is ok. If the stack is emptied, then something went wrong anyway & it is better to observe obviously invalid state of empty stack than to artificially obfuscate the problem.

There is no need to make these types "private".

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

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

kligarski

Looks good!

ios/gamma/stack/screen/RNSStackScreenComponentEventEmitter.mm

t0maboro · 2026-01-14T09:19:27Z

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

+  const preloadAction = React.useCallback((routeKey: string) => {
+    dispatch({ type: 'preload', routeName: routeKey, ctx: actionContext });


why in this specific case we're taking routeKey and then we're passing it to routeName, I'm just considering whether there's a chance to make dispatch call consistent with other actions without changing param name

You're right here. This is a mistake. The callback's param should be named routeName and not routeKey.

609a140

t0maboro · 2026-01-14T09:20:13Z

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

+    [dispatch, actionContext],
+  );
+
+  const preloadAction = React.useCallback((routeKey: string) => {


shouldn't we add PreloadActionMethod type here?

Thanks, added here: 609a140

t0maboro · 2026-01-14T09:26:34Z

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

+  }
+
+  const newState = [...state];
+  // NOTE: This modifes existing state, possibly impacting calculations done before new state is updated.


Suggested change

// NOTE: This modifes existing state, possibly impacting calculations done before new state is updated.

// NOTE: This modifies existing state, possibly impacting calculations done before new state is updated.

kkafar marked this pull request as draft January 5, 2026 11:07

kkafar added 14 commits January 7, 2026 18:28

Make type of children prop of StackHost not key-optional

26e13d4

It does not make sense to not specify children for `StackHost`.

Add useRenderDebugInfo utility hook

148098d

It logs component renders, mount & unmount. We can generalize / move it common code later. It seems useful.

Fix action name & move useRenderDebugInfo hook to

bbc35c2

`react-native-screens/private` This hook can be reused easily for different components while debugging. Seems useful enough to add it to private package.

Add basic support for dismiss in JS example code

c22fc98

Add basic support for dismiss in component code

e8a8685

This is rather a PoC than proper support. There are a couple of issues with current implementation.

Cleanup in component code

1037722

Add navigationStateReducerWithLogging that logs actions & state

ebd0633

This is debug-oriented utility.

Prevent pop action from executing when there is at most one attached

a8f7aa4

screen Previously I checked only whether there is screen at all. This could lead to corrupted state in obvious way, where all screens were detached!

Fix import in component code

7cdc89d

Cleanup code in reducer

d5db948

kkafar force-pushed the @kkafar/stack-development-2 branch from 102c8b2 to d5db948 Compare January 7, 2026 17:28

kkafar added 3 commits January 7, 2026 18:35

Fix swift linter

c1187d3

Remove routesByName

e230c61

It is not used anywhere in computation.

Use StackContainer name instead of StackContainerV2 + remove legacy impl

3c61b6d

kkafar commented Jan 7, 2026

View reviewed changes

kkafar mentioned this pull request Jan 12, 2026

fix(IOS): Fix non dismissible modal presentation #3415

Open

8 tasks

kkafar added 2 commits January 12, 2026 15:41

Add comment explaining why the route is appended to the end of the array

926017f

Remove the legacy code completely

225c828

kkafar requested review from kligarski, kmichalikk and t0maboro January 12, 2026 14:48

kkafar marked this pull request as ready for review January 12, 2026 14:50

Add comment for useRenderDebugInfo hook

e3a9432

kkafar changed the title ~~WIP PoC Implementation of new native stack on iOS~~ chore: add reference StackContainer implementation Jan 12, 2026

kligarski reviewed Jan 13, 2026

View reviewed changes

kmichalikk reviewed Jan 13, 2026

View reviewed changes

kkafar added 10 commits January 13, 2026 17:20

Remove the redundant comments

c4ef462

Use appropriate type for StackRouteConfig::Component

8770424

Remove __MODULE_KEEP__

4c237e3

Check whether all the routes have unique names

484c421

This is just a safe guard to catch possibly annoying to debug error. This commit also formats the code. I can not get my editor to save without formatting ^_^

Prevent name shadowing

043ac12

Remove debug log

9cdcfcd

A bit of cleanup

a3e9d95

Remove leftover implementation note comment

e4ead20

There is no need to make these types "private".

kkafar requested review from kligarski and kmichalikk January 13, 2026 20:41

kmichalikk reviewed Jan 14, 2026

View reviewed changes

apps/src/shared/gamma/containers/stack/reducer.tsx Outdated Show resolved Hide resolved

apps/src/shared/gamma/containers/stack/StackContainer.tsx Outdated Show resolved Hide resolved

kligarski approved these changes Jan 14, 2026

View reviewed changes

ios/gamma/stack/screen/RNSStackScreenComponentEventEmitter.mm Outdated Show resolved Hide resolved

kkafar added 3 commits January 14, 2026 10:13

Fix typo

2385e0b

Do not export createRouteFromConfig

c97a767

Fix event name in log message

868f14b

t0maboro approved these changes Jan 14, 2026

View reviewed changes

kkafar added 2 commits January 14, 2026 12:45

Fix typing mistake in preloadAction method param name

609a140

Fix another typo in comment

746c8cf

kkafar merged commit 696c640 into main Jan 14, 2026
8 checks passed

kkafar deleted the @kkafar/stack-development-2 branch January 14, 2026 11:49

		routeCopy.activityMode = 'attached';
		newState.push(routeCopy);

		ref?: React.RefObject<
		(React.Component<NativeProps> & ReactNativeElement) \| null

		const preloadAction = React.useCallback((routeKey: string) => {
		dispatch({ type: 'preload', routeName: routeKey, ctx: actionContext });

	// NOTE: This modifes existing state, possibly impacting calculations done before new state is updated.
	// NOTE: This modifies existing state, possibly impacting calculations done before new state is updated.

Uh oh!

chore: add reference StackContainer implementation #3518

chore: add reference StackContainer implementation #3518

Uh oh!

Conversation

kkafar commented Jan 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Changes

Uh oh!

kkafar left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kkafar Jan 7, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

kligarski left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

kligarski left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

chore: add reference `StackContainer` implementation #3518

chore: add reference `StackContainer` implementation #3518

kkafar commented Jan 5, 2026 •

edited

Loading

kkafar Jan 7, 2026 •

edited

Loading