Accessing context / creating snackbars

[luckyrat]

I'm testing out ReArch to see if it can be used on a real app and have stumbled early in the process.

Most apps need to be able to raise SnackBars and perform other operations using the build context in response to async events (such as an incoming websocket message or device hardware status change).

Since Capsules don't have access to the context, how am I supposed to be able to react to an async event?

In Bloc I would simply have a listener that sees when my Cubit state had changed and that listener provided me with the build context required to take actions like showing a snackbox. I see there are "listeners" in ReArch too but I can't work out how to use them in any way that provides the build context.

Alternatively there are WidgetSideEffects which sound like they are part of the solution but I can't work out how to trigger one in response to something happening in the Capsule graph.

Overall, despite reading much of this discussion forum, the MSc paper and the documentation website, I have found it hard to understand how the Capsule graph relates to the Flutter Widget tree so perhaps that is the underlying reason that I can't see any way forward at the moment.

Please can someone point me in the correct direction?

[GregoryConrad]

Hi! 👋

Capsules form a graph of business logic and app/global-level state, so naturally they don't have a BuildContext or some other means to access the UI directly. UI code is separated cleanly via flutter_rearch with RearchConsumers. Thus, you have to go to UI code to change the UI.

You have a few options here, in order of preference/testability:

1. Make a new RearchConsumer to show the app state as a part of itself (this could even be a SnackBar that you animate yourself, but often you use a more custom widget).
2. Snackbars are often for user-triggered events (which are often better suited by use.mutation anyways, read on). In this case, you can do:

onPressed: () async {
  await myAsyncFunction();
  if (!context.isMounted) return; // maybe it's context.mounted, can't remember
  ScaffoldMessenger.of(context).showSnackBar(...);
},

3. Make a new widget (and place it somewhere underneath your Scaffold) that listens to the capsule graph and shows a snack bar via a post frame callback when a capsule's state changes. I'd recommending limiting stuff like this as much as possible since it is imperative but if you must have a snackbar listen to some app state that is not user-triggerable (which I'd argue you probably shouldn't be doing anyways) instead of a better approach then this is how to do it. Quick example:

@rearchWidget
Widget snackbarListener(BuildContext context, WidgetHandle use, Widget child) {
  final data = use(myCapsule);
  final previousData = use.previous(data);
  if (data != previousData) {
    WidgetsBinding.instance!.addPostFrameCallback((_) {
      ScaffoldMessenger.of(context).showSnackBar(...);
    });
  }
  return child;
}

// elsewhere:
const Scaffold(
  body: SnackbarListener(
    child: MyOtherChild(),
  ),
);

SnackBars are a bit of an odd one since they have an imperative API instead of a declarative one. We'd really expect a:

Scaffold(
  snackbar: SnackBar(...) // or null to hide, perhaps
);

No clue why Flutter didn't do that (maybe ease of use in simple situations), but it's a design anomaly compared to the rest of the framework.

how am I supposed to be able to react to an async event?

Typically this is done via:
use.future, use.stream, and use.mutation (mutations are very powerful, allowing you to react to user-triggered events!). There are also use.invalidatableFuture and use.refreshableFuture, but those are less common than the previous 3.

[GregoryConrad]

Also to help answer your confusion about the capsule graph vs widget tree:

The capsule graph is a Dart-only implementation (no flutter). The widget tree is able to "look" into the capsule graph and get updated when the capsule graph changes. They are separate entities; if you're familiar with get_it, think of the capsule graph (housed in a CapsuleContainer) as analogous to GetIt.instance and then the widgets as a separate entity that can reference it.

Ideally, the widget tree would actually be built into the capsule graph to make this all a very seamless system, but since Flutter already has Element, this isn't possible in Flutter. I'm experimenting with /packages/ramen for this purpose, at least for web & HTML.

[luckyrat]

Hi!

Thanks for the quick and helpful responses.

This is the usual way of consuming global app state, right? I think I get how that works and yes it is very neat and testable when possible but I don't think it can work when the imperative parts of the Flutter API need to be invoked (such as SnackBar). I take your point that I could re-invent the SnackBar in a declarative fashion or find some library that has already done this but I am also interested in the broader understanding of where any challenges may appear if using Rearch at large scale so appreciate the additional info you provided.

I think the name of RearchConsumer is something that has confused me. Maybe since in Bloc a BlocConsumer is an enhanced version of a BlocBuilder which can also listen to changes and thus respond to events. Not saying there is anything wrong with your naming choice, just providing some context to maybe help understand an area of potential confusion for people with prior knowledge of Bloc/Cubit.

Yep, it's mounted.

I've been using use.mutation as part of my example app including the "Sign In Flow" snippet and can see how neat the user-initiated story is using this approach. However I wanted to verify a solution for externally triggered events too - in fact even some user-triggered events might benefit from a clean separation of the initial user action (e.g. reporting a timeout after the context has since been destroyed, rather than just ignoring it as is typical with the context.mounted check). Definitely an edge case where there is almost always a better UX that doesn't require an imperative SnackBar but I suppose it's testament to all your hard work so far that I'm even contemplating the exceptions to "almost always"!

For the "simple path" of a user-triggered event, I did have one question about the implementation I came up with:

...
final (state: signInState, mutate: mutateSignIn, clear: _) = use.mutation<SignInResult>();
final rawSignIn = use(signInAction);

Future<void> signIn() async {
  final signInResultFuture = rawSignIn(email(), password());
  final sm = ScaffoldMessenger.of(context);

  // Is it OK to mutate the Future and then await it again to access the result?
  mutateSignIn(signInResultFuture);
  final signInResult = await signInResultFuture;

  if (signInResult.snack) {
    sm.showSnackBar(const SnackBar(
      content: Text('sign in snack response'),
    ));
  }
}

By updating a data capsule after the mutation completes (awaiting the result as in the above code) and using this SnackbarListener I was able to get the SnackBar to appear without worrying about whether the context had already been disposed. I think this proves the concept that there is a way to trigger a snackbar in response to a data change in the capsule graph (and thus any other side-effect I think). As you suggest, it's something I'll do rarely but I'm happy that I now understand how to develop this sort of escape hatch in case similar challenges come up as the app grows in complexity.

No clue why Flutter didn't do that (maybe ease of use in simple situations), but it's a design anomaly compared to the rest of the framework.

That's reassuring. I've never worked with an application architecture that doesn't hit some edge cases when meeting anomalous decisions in dependencies/frameworks and I had hoped this was just one of those rare situations. It definitely looks like I just stumbled across one of the more challenging integration points early on but great to see a path forward even in such cases.

There's also a scaffoldMessengerKey property on MaterialApp but it feels like global keys are a bit too far from the idea of a primarily functional architecture. In any case, maybe there are other situations where one needs access to BuildContext in response to an async event so I wanted to understand the broader implications even if there is some equally imperfect but easier solution just for Snackbars via a global key.

By the way, I think another area of nomenclature that might have contributed to my confusion is the overload of "build" in terms of building the Flutter UI Widgets as well as building the Capsules. I can't point to any documentation or thing to change at this point but thought it worth mentioning as something to keep in mind when next refreshing the docs or writing about the architecture.

[GregoryConrad]

This is the usual way of consuming global app state, right? I think I get how that works and yes it is very neat and testable when possible but I don't think it can work when the imperative parts of the Flutter API need to be invoked (such as SnackBar).

Yup! You got it. The issue is those imperative parts that are one-offs, and is why we need some funky workarounds sometimes (like the third option I gave in my original comment with the SnackbarListener widget).

For the "simple path" of a user-triggered event, I did have one question about the implementation I came up with:

That's almost what I'd do; here is what I'd do:

void signIn() {
  // Not sure if this is safe if context/scaffold leaves the widget tree,
  // but if it was previously working for you then no worries (otherwise do a mounted check):
  final sm = ScaffoldMessenger.of(context);

  mutateSignIn(() async {
    final signInResult = await rawSignIn(email(), password());
    if (signInResult.snack) {
      sm.showSnackBar(const SnackBar(
        content: Text('sign in snack response'),
      ));
    }
    return signInResult;
  }());
}

That way the mutation encompasses the entire execution process. Wish Dart had async blocks instead of needing to make a closure, but alas.

I think the name of RearchConsumer is something that has confused me.

I thought about naming it just "Consumer" when I originally created the library, but I settled on a Rearch prefix for all of the widgets, if I recall correctly, so it'd be easy to find them in an editor. This also won't be an issue for too much longer since the macro I've got in #89 will just generate the class for you.

As you suggest, it's something I'll do rarely but I'm happy that I now understand how to develop this sort of escape hatch in case similar challenges come up as the app grows in complexity.

Glad to hear it! Sometimes when interacting with imperative router APIs (or some other random APIs) you may need some other escape hatches, such as accessing a container directly to read capsules. For situations like that, take a look at CapsuleContainerProvider.containerOf(context) so you don't get stuck. There is another function or two I'm forgetting to list here under "escape hatch", but if you run into a problem like that, feel free to look through/make a new discussion post and I can point you in the right direction.

There's also a scaffoldMessengerKey property on MaterialApp but it feels like global keys are a bit too far from the idea of a primarily functional architecture.

Had no clue that existed. Alas, I treat GlobalKeys like the plague, but if you really need it, then I guess it's there 😆

Just try to avoid GlobalKeys when you can since they are essentially just static global variables, which themselves are an anti-pattern outside of just ReArch (accessing them from a service locater/dependency injection is fine though--you just need some level of dependency inversion).

I can't point to any documentation or thing to change at this point but thought it worth mentioning as something to keep in mind when next refreshing the docs or writing about the architecture.

Thanks for the heads up. The notion of a capsule "building" was derived from Riverpod and how it has "builds" as well, which was derived from Flutter's whole Widget.build. While a Widget "builds" UI, capsules instead "build" some sort of state/app logic. That might be worth tossing in the docs

[luckyrat]

// Not sure if this is safe if context/scaffold leaves the widget tree,

It works when context is unmounted but I expect it would break if the Scaffold is removed too - probably a risk in many apps but not a concern for me at the moment.

Your code suggestion looks good. What are the advantages of wrapping the entire process in the mutation?

I've had to use a GlobalKey in another app without DI and thankfully it's not caused any practical problems yet but previous experience of similar patterns does make me think it's only a matter of time/scale before a problem bites so I am already keen to avoid them for as long as possible in any new project.

[GregoryConrad]

What are the advantages of wrapping the entire process in the mutation?

When the UI rebuilds as a result of the mutation finishing, you know the entire process has completed, including any side effects (like displaying a temporary SnackBar). It just improves testability, because you are testing the business logic (sign in) and the UI changes (showing snackbar), instead of just the business logic and hoping the UI is updated too.