Componentization by adding a CircuitPresenterState

[dandc87]

I keep wanting to use Circuit for reusable, nested sub-"screen" components, a la React Components, but I feel like the current API is mostly (exclusively?) designed around "screens" and navigation between them. And I think there's a "simple" (but quite breaking) API change that could add a lot of the flexibility I am wanting.

Proposal

• Add a CircuitPresenterState, mirroring CircuitUiState
• Change Presenter.present to take a (type-argument-ed) CircuitPresenterState
• Add a CircuitPresenterState type argument to Screen
  • Also add a factory function declaration (and probably a Saver too?)
• Add a CircuitPresenterState argument to CircuitContent
• Add a CircuitPresenterState property to BackStack.Record (and expose from Navigator?)

Motivating Examples

Smart Buttons

Say my app is a social one, and "add as friend" buttons are plastered everywhere, especially in list items! I'm a lazy developer and don't want to wire all of the boilerplate for these on every screen. I could use a Screen, but Product wants different "already friends" behavior for different screens! I wish I could pass in an an enum and an event sink to easily customize behavior.

data class FriendingButtonPresenterState(
  val type: AlreadyFriendsType,
  val onClick: () -> Unit,
) : CircuitPresenterState

CircuitContent(
  screen = FriendingButton(userId),
  presenterState = FriendingButtonPresenterState(
    type = AddToGroup,
    onClick = { state.eventSink(AddToGroup(userId)) },
  ),
)

Scroll Tab's Content on Second Click

A nice UX is scrolling to the top of a tab if you click on the tab again. But if my tabs are each just CircuitContent() (or NavigableCircuitContent), I don't have access to the scroll state. I could maybe have the host Presenter be an aggregating Presenter, but that would Compose all the off-screen presenters too! I wish I could just hoist out the scroll states:

data class FriendsTabPresenterState(
  val listState: LazyListState,
) : CircuitPresenterState

data class LobbyState(
  val friendsTab: FriendsTabPresenterState,
  val homeTab: HomeTabPresenterState,
  // ...
) : CircuitUiState

CircuitContent(
  screen = FriendsTab(),
  presenterState = state.friendsTab,
)

Deeplink as an Action

Say the app is warm and cozy in the background and wakes up with onNewIntent() from a push notification. The user just got a reply to one of their comments! Due to crazy Product reasons, the comments are an integrated "sheet" within the main content Screen. So for a really nice UX, not only do we need to modify the back stack to go to the right screen, we also want to open the comments "sheet", and even scroll down the list to see the new reply.

// Very pseudo-code, much fake
fun Navigator.goToReply(pageId: String, replyId: String) {
  val topScreen = peek()?.screen
  if (topScreen !is ContentPage || topScreen.id != pageId) {
    resetToLobby()
    push(ContentPage(pageId))
  }
  val record = peek() as NavigationRecord<ContentPage, ContentPagePresenterState>
  record.presenterState.commentsSheetState.openComments(idToFocus = replyId)
}

Migration Path

The changes don't have to be that invasive to existing code beyond some lower-level API breaking. I've been hacking at this a bit today, and if we don't want to completely break downstream

• Instead of adding a type parameter to existing interfaces, add super-interfaces and existing ones
• APIs that current take a Screen can take Component<T> and a T defaulted to the Component.newPresenterState()

@Immutable
interface Component<S: CircuitPresenterState> {
  fun newPresenterState(): S
  fun presenterStateSaver(): Saver<State, Any> get() = neverSave()
}

interface Screen : Component<CircuitPresenterState.NoState> {
  override fun newPresenterState() = CircuitPresenterState.NoState
}

@Immutable
interface ComponentPresenter<State: CircuitPresenterState, UiState: CircuitUiState> {
  @Composable fun present(state: CircuitPresenterState): CircuitUiState
}

interface Presenter<UiState: CircuitUiState> : Component<NoState, UiState> {
  @Composable fun present(): UiState
  @Composable override fun present(state: CircuitInputState.NoState): UiState = present()
}

// NavigatorImpl.kt
override fun <C : Component<S>, S : CircuitPresenterState> goTo(screen: C): Boolean {
  // The "owner" of the state is the backstack,
  // to get the state you have to read it from records
  return backStack.push(screen, screen.newPresenterState())
}

Conclusion

I'm opening this for discussion because I was half-way down the road of reimplementing Circuit but with this change, and I thought I should see if upstream and the community was interested or had better ideas.

I think the main argument against is that there are other ways to accomplish my examples, with CompositionLocal or some other kind of injected side channel. But I feel like this is more elegant, and more in line with Compose state hoisting.

Also, if the proposal is acceptable in some form, I would be willing to contribute the work for it 💪

edit: minor fixes after rereading

[ZacSweers]

I don't think this proposal is one we would accept. Each of the scenarios you describe actually have better existing patterns in Circuit.

Smart Buttons

This should be solved at your data layer. Your button UIs should not maintain the state themselves, they should derive it from your underlying data layer (such as a repository). Assuming all buttons read from the same data source, they should all update accordingly.

Scroll tabs contents

There's different ways to solve this but the key point is that scrolling UI isn't a presenter concern. It's a UI state thing. I've solved this by exposing a composition local that scrollable UIs can observe to get signals to scroll to top.

Deeplink as an Action

If this is an expected scenario, I would expose new intents as an observable source and collect this in your presenter.

---

I think your proposal tries to solve these cases by pushing more state across presenter boundaries through presenters themselves, but in an untyped and fairly limited way. Circuit really wants you to use a good data layer and to focus on deriving your state from that. Presenters aren't the source of truth, they're just translators.

[dandc87]

After a night's sleep, I see how this proposal is really just avoiding data layer abstractions. But I have larger philosophical questions based on your response:

they should derive it from your underlying data layer

The idea with this example is more the intermediate states I wish to deduplicate, e.g. setting a isSendingRequest to show/hide a spinner. What I'm currently doing on multiple screens is managing sets of ids for work-in-progress; copy-pasting the same Event handling everywhere. Is there a Circuit solution to reduce my copy-pasting? Is it just nested Presenters?

Your button UIs should not maintain the state themselves

Are you saying that "componentizing" in general is discouraged (or at least not a use case for CircuitContent), even if the buttons could be modeled as a Screen? How do you square this with nested navigation? In your view, when does "a bit of UI" become a Screen?

... scrolling UI isn't a presenter concern. It's a UI state thing.

This isn't true in the limit though, right? If business logic dictated I scrolled based on a data layer event, but would otherwise not change data used to render UI, my choices are 1) hoist the scroll state into the Presenter or 2) add extra state and events as a secondary "source of truth" for where scroll position should be. For the deeplinking example case (using the data layer source you recommended) you'd argue that I should have a scrollToReplyId property on my State for the UI to observe, and an Event to signal scroll did happen and to clear the property? Even if there are many of these flags and events?