Circuit

https://slackhq.github.io/circuit
Admin
Circuit is a simple, lightweight, and extensible framework for building Kotlin applications with...
Tokens:1,975,257
Snippets:12,493
Trust Score:8.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### iOS Development Setup

Source: https://slackhq.github.io/circuit/contributing

Instructions for setting up the iOS development environment for the Circuit project. This includes installing dependencies using Bundler and SwiftFormat.

```bash
bundle install
brew install swiftformat
```

--------------------------------

### Circuit Setup in main.kt (Wasm)

Source: https://slackhq.github.io/circuit/tutorial

Demonstrates the Circuit setup for a WebAssembly application, including CircuitCompositionLocals.

```kotlin
fun main() {
    val circuit = Circuit.Builder()
        // ...
        .build()

    onWasmReady {
        Window("Inbox") {
            CircuitCompositionLocals(circuit) {
                // ...
            }
        }
    }
}
```

--------------------------------

### Integrating Circuit with CircuitCompositionLocals

Source: https://slackhq.github.io/circuit/setup

Shows how to use CircuitCompositionLocals to expose the Circuit configuration to child composables and render content using CircuitContent. This is the primary way to get started with Circuit.

```kotlin
CircuitCompositionLocals(circuit){
CircuitContent(AddFavoritesScreen())
}
```

--------------------------------

### Example Circuit Navigator Setup

Source: https://slackhq.github.io/circuit/circuitx/navigation

Demonstrates setting up an InterceptingNavigator with multiple interceptors, event listeners, and a failure notifier within a Jetpack Compose application.

```kotlin
valinterceptors=
persistentListOf(
// Order matters! First interceptor is first handle navigation
AndroidScreenAwareNavigationInterceptor(context),
AuthInterceptor(authManager),
UrlRewriteInterceptor,
)

valeventListeners=
persistentListOf(
LoggingNavigationEventListener,
AnalyticsNavigationEventListener(analytics,crashReporter),
)

valnotifier=AnalyticsFailureNotifier(analytics)
valcircuit=buildCircuit()

@Composable
funApp(){
valbackStack=rememberSaveableBackStack(HomeScreen)
valbaseNavigator=rememberCircuitNavigator(backStack)

// Create the intercepting navigator with all our interceptors
valnavigator=
rememberInterceptingNavigator(
navigator=baseNavigator,
interceptors=interceptors,
eventListeners=eventListeners,
notifier=notifier,
)

// Use the navigator with your Circuit
CircuitCompositionLocals(circuit){
NavigableCircuitContent(navigator=navigator,backStack=backStack)
}
}
```

--------------------------------

### Basic Navigation Setup

Source: https://slackhq.github.io/circuit/navigation

Demonstrates the fundamental setup for navigation using `rememberSaveableBackStack` and `rememberCircuitNavigator` with `NavigableCircuitContent`.

```kotlin
setContent{
val backStack = rememberSaveableBackStack(root = HomeScreen)
val navigator = rememberCircuitNavigator(backStack)
NavigableCircuitContent(navigator, backStack)
}
```

--------------------------------

### Circuit Setup in main.kt (Desktop)

Source: https://slackhq.github.io/circuit/tutorial

Illustrates setting up the Circuit instance and integrating it with CircuitCompositionLocals for a desktop application.

```kotlin
fun main() {
    val circuit = Circuit.Builder()
        // ...
        .build()

    application {
        Window(title = "Inbox", onCloseRequest = ::exitApplication) {
            CircuitCompositionLocals(circuit) {
                // ...
            }
        }
    }
}
```

--------------------------------

### Putting it all together

Source: https://slackhq.github.io/circuit/tutorial

Combines the creation of the backstack, navigator, and CircuitCompositionLocals with NavigableCircuitContent for a complete navigation setup.

```kotlin
val backStack = rememberSaveableBackStack(root = InboxScreen)
val navigator = rememberCircuitNavigator(backStack) {
    // Do something when the root screen is popped, usually exiting the app
}
CircuitCompositionLocals(circuit) {
    NavigableCircuitContent(navigator = navigator, backStack = backStack)
}
```

--------------------------------

### Circuit Setup in MainActivity (Android)

Source: https://slackhq.github.io/circuit/tutorial

Shows how to initialize the Circuit instance and provide it to the composition hierarchy using CircuitCompositionLocals within an Android Activity.

```kotlin
class MainActivity {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        val circuit = Circuit.Builder()
            // ...
            .build()

        setContent {
            CircuitCompositionLocals(circuit) {
                // ...
            }
        }
    }
}
```

--------------------------------

### Circuit Presenter and UI Example

Source: https://slackhq.github.io/circuit/testing

An example demonstrating the structure of a Circuit Presenter and its corresponding UI Composable function. It includes data classes for state and events, and logic for handling user interactions.

```kotlin
data class Favorite(val id: Long, ...)

@Parcelable
data object FavoritesScreen : Screen {
    sealed interface State : CircuitUiState {
        data object Loading : State
        data object NoFavorites : State
        data class Results(
            val list: List<Favorite>,
            val eventSink: (Event) -> Unit
        ) : State
    }

    sealed interface Event : CircuitUiEvent {
        data class ClickFavorite(val id: Long) : Event
    }
}

class FavoritesPresenter @Inject constructor(
    private val navigator: Navigator,
    private val repo: FavoritesRepository
) : Presenter<FavoritesScreen.State> {
    @Composable
    override fun present(): FavoritesScreen.State {
        val favorites by produceState<List<Favorite>?>(null) {
            value = repo.getFavorites()
        }

        return when {
            favorites == null -> Loading
            favorites.isEmpty() -> NoFavorites
            else ->
                Results(favorites) { event ->
                    when (event) {
                        is ClickFavorite -> navigator.goTo(FavoriteScreen(event.id))
                    }
                }
        }
    }
}

@Composable
fun FavoritesList(state: FavoritesScreen.State) {
    when (state) {
        Loading -> Text(text = stringResource(R.string.loading_favorites))
        NoFavorites -> Text(
            modifier = Modifier.testTag("no favorites"),
            text = stringResource(R.string.no_favorites)
        )
        is Results -> {
            Text(text = "Your Favorites")
            LazyColumn {
                items(state.list) { Favorite(it, state.eventSink) }
            }
        }
    }
}

@Composable
private fun Favorite(favorite: Favorite, eventSink: (FavoritesScreen.Event) -> Unit) {
    Row(
        modifier = Modifier.testTag("favorite"),
        onClick = { eventSink(ClickFavorite(favorite.id)) }
    ) {
        Image(
            drawable = favorite.drawable,
            contentDescription = stringResource(R.string.favorite_image_desc)
        )
        Text(text = favorite.name)
        Text(text = favorite.date)
    }
}
```

--------------------------------

### Profile UI Example

Source: https://slackhq.github.io/circuit/api/0.x/circuit-runtime-presenter/com.slack.circuit.runtime.presenter/-presenter/-factory/index

A visual representation of the Profile UI, illustrating the different presenter components and their relationships.

```text
                              ┌────────────────────┐
                         ┌─── │                    │
                         │    ├────────────────────┤◄──┐
                         │    │ X                  │   │
                         │    │                    │ ProfileHeaderPresenter
                         │    │ Fred Rogers        │   │
                         │    ├────────────────────┤◄──┘
                         │    │ ┌───────┐  ┌────┐  │
    ProfilePresenterFactory   │ │Message│  │Call│◄─┼─── ProfileActionsPresenter
                         │    │ └───────┘  └────┘  │
                         │    │                    │
                         │    │  - - - - - - - - ◄─┼────┐
                         │    │  - - - - - - - -   │    │
                         │    │  - - - - - - - -   │  ProfileDetailsPresenter
                         │    │  - - - - - - - - ◄─┼────┘
                         └─── │                    │
                              └────────────────────┘
```

--------------------------------

### Navigator goTo Example

Source: https://slackhq.github.io/circuit/navigation

Illustrates how a presenter can use a `navigator` instance to navigate to a new screen, passing necessary data.

```kotlin
fun showAddFavorites() {
    navigator.goTo(
        AddFavorites(
            externalId = uuidGenerator.generate()
        )
    )
}
```

--------------------------------

### Example Screen Implementations

Source: https://slackhq.github.io/circuit/screen

Demonstrates creating simple marker data objects and data classes with parameters that implement the Screen interface.

```kotlin
@Parcelize
data object HomeScreen:Screen

@Parcelize
data class AddFavoritesScreen(val externalId: UUID):Screen
```

--------------------------------

### AndroidScreenStarter Kotlin Implementation

Source: https://slackhq.github.io/circuit/api/0.x/circuitx/android/com.slack.circuitx.android/-android-screen-starter/start

An abstract function signature for starting an AndroidScreen using the AndroidScreenStarter in Kotlin.

```Kotlin
abstract fun start(screen: AndroidScreen): Boolean
```

--------------------------------

### Rendering a Screen with CircuitContent

Source: https://slackhq.github.io/circuit/tutorial

Provides an example of using CircuitContent to render a specific screen, relying on the Circuit instance provided through CircuitCompositionLocals.

```kotlin
CircuitCompositionLocals(circuit) {
    CircuitContent(InboxScreen)
}
```

--------------------------------

### Circuit Foundation Installation

Source: https://slackhq.github.io/circuit/setup

This snippet shows how to add the circuit-foundation dependency to your project for core Circuit artifacts. Replace '<version>' with the desired version number.

```kotlin
dependencies{
implementation("com.slack.circuit:circuit-foundation:<version>")
}
```

--------------------------------

### Circuit Runtime UI Content Implementation

Source: https://slackhq.github.io/circuit/api/0.x/circuit-runtime-ui/com.slack.circuit.runtime.ui/-ui/-content

Example implementation of the Content composable for the Circuit runtime UI.

```kotlin
@Composable
abstract fun Content(state: UiState, modifier: Modifier)
```

--------------------------------

### AndroidScreenStarter API

Source: https://slackhq.github.io/circuit/api/0.x/circuitx/android/com.slack.circuitx.android/-android-screen-starter/start

API documentation for the AndroidScreenStarter interface, which handles starting Android screens within the CircuitX framework. It defines the contract for initiating screen transitions.

```APIDOC
AndroidScreenStarter:
  Interface for starting Android screens.

  start(screen: AndroidScreen): Boolean
    Starts the given AndroidScreen.
    Parameters:
      screen: The AndroidScreen to start.
    Returns:
      Boolean: True if the screen was started successfully, false otherwise.
```

--------------------------------

### InterceptingNavigator Setup

Source: https://slackhq.github.io/circuit/circuitx/navigation

Demonstrates how to set up an InterceptingNavigator using rememberInterceptingNavigator. This involves providing a base navigator, interceptors, event listeners, and a failure notifier.

```kotlin
val backStack = rememberSaveableBackStack(Screen)
val navigator = rememberCircuitNavigator(backStack)
val interceptingNavigator = rememberInterceptingNavigator(navigator, interceptors, eventListeners, notifier)
NavigableCircuitContent(navigator = interceptingNavigator, backStack = backStack)
```

--------------------------------

### Screen Interface and Usage

Source: https://slackhq.github.io/circuit/api/0.x/circuit-runtime-screen/com.slack.circuit.runtime.screen/-screen/index

Defines the `Screen` interface, which serves as a key for presenters and UI components. It includes examples of creating screen data classes and navigating between them.

```APIDOC
Screen
  - Represents an individual screen, used as a key for Presenter.Factory and Ui.Factory.
  - Screens can be simple sentinel data object types or data classes with information.
  - Screens with information should contain the minimum amount of data needed for the target presenter to begin presenting state.

Example Usage:
```kotlin
data class AddFavorites(
  val externalId: UUID,
) : Screen

fun showAddFavorites() {
 navigator.goTo(
   AddFavorites(
     externalId = uuidGenerator.generate()
   )
 )
}
```

- Inheritors: StaticScreen
```

--------------------------------

### Counter Example in Kotlin

Source: https://slackhq.github.io/circuit/index

Demonstrates a simple Counter screen using Circuit's Presenter and Ui components. It includes state management for the count and event handling for increment/decrement actions.

```kotlin
@Parcelize
dataobject CounterScreen : Screen {
    dataclass CounterState(
        val count: Int,
        val eventSink: (CounterEvent) -> Unit
    ) : CircuitUiState

    sealed interface CounterEvent : CircuitUiEvent {
        dataobject Increment : CounterEvent
        dataobject Decrement : CounterEvent
    }
}

@CircuitInject(CounterScreen::class, AppScope::class)
@Composable
fun CounterPresenter(): CounterState {
    var count by rememberSaveable { mutableStateOf(0) }

    return CounterState(count) { event ->
        when (event) {
            CounterEvent.Increment -> count++
            CounterEvent.Decrement -> count--
        }
    }
}

@CircuitInject(CounterScreen::class, AppScope::class)
@Composable
fun Counter(state: CounterState) {
    Box(Modifier.fillMaxSize()) {
        Column(Modifier.align(Alignment.Center)) {
            Text(
                modifier = Modifier.align(CenterHorizontally),
                text = "Count: ${state.count}",
                style = MaterialTheme.typography.displayLarge
            )
            Spacer(modifier = Modifier.height(16.dp))
            Button(
                modifier = Modifier.align(CenterHorizontally),
                onClick = { state.eventSink(CounterEvent.Increment) }
            ) { Icon(rememberVectorPainter(Icons.Filled.Add), "Increment") }
            Button(
                modifier = Modifier.align(CenterHorizontally),
                onClick = { state.eventSink(CounterEvent.Decrement) }
            ) { Icon(rememberVectorPainter(Icons.Filled.Remove), "Decrement") }
        }
    }
}
```

--------------------------------

### Circuit Instance Creation and Configuration

Source: https://slackhq.github.io/circuit/setup

Demonstrates how to create a Circuit instance with custom UI and Presenter factories. The Circuit instance manages common configuration and factories.

```kotlin
val circuit=Circuit.Builder()
.addUiFactory(AddFavoritesUiFactory())
.addPresenterFactory(AddFavoritesPresenterFactory())
.build()
```

--------------------------------

### Circuit Code Generation Installation

Source: https://slackhq.github.io/circuit/code-gen

Instructions for installing the KSP-based code generation solution for Circuit. This setup is crucial for leveraging Circuit's capabilities in reducing dependency injection boilerplate.

```kotlin
/* Installation instructions would typically go here, likely involving Gradle or Maven dependencies. */
// Example for Gradle:
// ksp 'com.slack.circuit:circuit-ksp:x.y.z'
```

--------------------------------

### Shared Element Transition Setup Example

Source: https://slackhq.github.io/circuit/shared-elements

Illustrates how to use SharedElementTransitionLayout to provide a SharedTransitionScope for nested Composables, enabling shared element transitions.

```kotlin
Composable
fun MyScreen() {
    SharedElementTransitionLayout {
        // Your Composables that use shared element modifiers go here
        // Access SharedTransitionScope and AnimatedVisibilityScope within this block
    }
}
```

--------------------------------

### Circuit API Documentation

Source: https://slackhq.github.io/circuit/setup

Provides an overview of the Circuit API, including key components like Circuit, Circuit.Builder, UiFactory, PresenterFactory, CircuitCompositionLocals, and CircuitContent.

```APIDOC
Circuit:
  A core component that manages the application's state and UI.

Circuit.Builder:
  Used to construct a Circuit instance.
  Methods:
    addUiFactory(uiFactory: UiFactory): Builder
      Adds a UI factory to the builder.
    addPresenterFactory(presenterFactory: PresenterFactory): Builder
      Adds a presenter factory to the builder.
    build(): Circuit
      Builds and returns the Circuit instance.

UiFactory:
  An interface for creating UI components.

PresenterFactory:
  An interface for creating Presenters.

CircuitCompositionLocals:
  Provides Circuit dependencies to composables via CompositionLocal.
  Usage:
    CircuitCompositionLocals(circuit) { ... }

CircuitContent:
  A composable that renders the UI for a given Screen.
  Parameters:
    screen: The Screen to render.
```

--------------------------------

### AnimatedScreenTransform Example

Source: https://slackhq.github.io/circuit/api/0.x/circuit-foundation/com.slack.circuit.foundation.animation/-animated-screen-transform/index

Example implementation of AnimatedScreenTransform for custom screen transitions.

```kotlin
object CustomScreenAnimatedTransform : AnimatedScreenTransform {

  override fun AnimatedContentTransitionScope<AnimatedNavState>.enterTransition(
    animatedNavEvent: AnimatedNavEvent
  ): EnterTransition? {
    // Coming from `HomeScreen` we override the transition to slide in horizontally.
    return if (initialState.screen is HomeScreen) slideInHorizontally() else null
  }

  override fun AnimatedContentTransitionScope<AnimatedNavState>.exitTransition(
    animatedNavEvent: AnimatedNavEvent
  ): ExitTransition? {
    // Going to `HomeScreen` we override the transition fade out.
    return if (targetState.screen is HomeScreen) fadeOut() else null
  }
}
```

--------------------------------

### Circuit Foundation EventListener start

Source: https://slackhq.github.io/circuit/api/0.x/circuit-foundation/com.slack.circuit.foundation/-event-listener/start

The 'start' method is called once before doing any processing for the requested circuit.

```Kotlin
open fun start()
  - Called once before doing any processing for the requested circuit.
```

--------------------------------

### Example Usage of OverlayHost

Source: https://slackhq.github.io/circuit/api/0.x/circuit-overlay/com.slack.circuit.overlay/-overlay-host/index

An example of how to create an extension function on OverlayHost to show a confirmation dialog and await a result.

```kotlin
private suspend fun OverlayHost.confirm(message: String): ConfirmationResult {
  return show(ConfirmationOverlay(message))
}
```

--------------------------------

### Creating a Circuit Instance

Source: https://slackhq.github.io/circuit/tutorial

Demonstrates how to create a Circuit instance using the Circuit.Builder pattern, adding a presenter and a UI for a specific screen.

```kotlin
val emailRepository = EmailRepository()
val circuit: Circuit = Circuit.Builder()
    .addPresenter<InboxScreen, InboxScreen.State>(InboxPresenter(emailRepository))
    .addUi<InboxScreen, InboxScreen.State> { state, modifier -> Inbox(state, modifier) }
    .build()
```

--------------------------------

### Custom Decorator Example

Source: https://slackhq.github.io/circuit/api/0.x/circuit-foundation/com.slack.circuit.foundation.animation/-animated-nav-decorator/index

An example implementation of AnimatedNavDecorator for custom navigation transitions, including vertical slide and fade effects.

```kotlin
data class CustomNavState<T : NavArgument>(
  val args: ImmutableList<T>,
  override val screen: Screen = args.first().screen,
  override val rootScreen: Screen = args.last().screen,
) : AnimatedNavState

class CustomDecorator<T : NavArgument>() : AnimatedNavDecorator<T, CustomNavState<T>> {

  override fun AnimatedContentTransitionScope<AnimatedNavState>.transitionSpec(
    animatedNavEvent: AnimatedNavEvent
  ): ContentTransform {
    return slideInVertically() + fadeIn() togetherWith slideOutVertically() + fadeOut()
  }

  override fun targetState(args: ImmutableList<T>): CustomNavState<T> {
    // Logic to build your custom navigation state
    return CustomNavState(args)
  }

  @Composable
  override fun updateTransition(
    args: ImmutableList<T>,
  ): Transition<CustomNavState<T>> {
    val targetState = targetState(args)
    return updateTransition(targetState = targetState, label = "CustomDecoratorTransition")
  }

  @Composable
  override fun AnimatedContentScope.Decoration(
    targetState: CustomNavState<T>,
    innerContent: @Composable (T) -> Unit,
  ) {
    Box(modifier = Modifier.fillMaxSize()) { innerContent(targetState.args.first()) }
  }
}
```

--------------------------------

### Example Usage of produceRetainedState

Source: https://slackhq.github.io/circuit/api/0.x/circuit-retained/com.slack.circuit.retained/produce-retained-state

An example demonstrating how to use `produceRetainedState` within a Composable function to observe data from a repository and update the UI state.

```kotlin
@Composable
fun FavoritesPresenter(favoritesRepository: FavoritesRepository): State {
  val state by produceRetainedState<UiState<List<Person>>>(UiState.Loading, favoritesRepository) {
    favoritesRepository.people
      .map { UiState.Data(it) }
      .collect { value = it }
  }
  return state
}
```

--------------------------------

### Circuit Code Generation Installation

Source: https://slackhq.github.io/circuit/code-gen

Instructions for installing the Circuit code generation plugin and dependencies in a Gradle project. It specifies the necessary KSP plugins and API dependencies.

```gradle
plugins{
id("com.google.devtools.ksp")
}

dependencies{
api("com.slack.circuit:circuit-codegen-annotations:<version>")
ksp("com.slack.circuit:circuit-codegen:<version>")
}
```

--------------------------------

### produceRetainedState Usage Example

Source: https://slackhq.github.io/circuit/api/0.x/circuit-retained/com.slack.circuit.retained/produce-retained-state

An example demonstrating how to use produceRetainedState to observe external data from a repository and update the UI state. It shows how to map data and collect values into the state.

```kotlin
@Composable
fun FavoritesPresenter(favoritesRepository: FavoritesRepository): State {
  val state by produceRetainedState<UiState<List<Person>>>(UiState.Loading, favoritesRepository) {
    favoritesRepository.people
      .map { UiState.Data(it) }
      .collect { value = it }
  }
  return state
}
```

--------------------------------

### State Retention Example (Configuration Changes)

Source: https://slackhq.github.io/circuit/api/0.x/circuit-retained/com.slack.circuit.retained/remember-retained

This example demonstrates how to use `rememberRetained` with `mutableStateOf` to retain a `CounterState` across configuration changes. The state will survive screen rotations but not process death.

```kotlin
@Composable
override fun present(): CounterState {
  var state by rememberRetained { mutableStateOf(CounterState(0)) }

  return CounterState(count) { event ->
    when (event) {
      is CounterEvent.Increment -> state = state.copy(count = state.count + 1)
      is CounterEvent.Decrement -> state = state.copy(count = state.count - 1)
    }
  }
}
```

--------------------------------

### Circuit Platform Support

Source: https://slackhq.github.io/circuit/setup

Details the availability of Circuit features across different platforms: Android, JVM, iOS, and JavaScript. Indicates support with ✅ (Available), ❌ (Not available), or – (Not applicable).

```markdown
Feature | Android | JVM | iOS | JS | Notes  
---|---|---|---|---|---
`Backstack` | ✅ | ✅ | ✅ | ✅ |   
`CircuitContent` | ✅ | ✅ | ✅ | ✅ |   
`ContentWithOverlays` | ✅ | ✅ | ✅ | ✅ |   
`NavigableCircuitContent` | ✅ | ✅ | ✅ | ✅ |   
`Navigator` | ✅ | ✅ | ✅ | ✅ |   
`SaveableBackstack` | ✅ | ✅ | ✅ | ✅ | Saveable is a no-op on non-android.  
`rememberCircuitNavigator` | ✅ | ✅ | ✅ | ✅ |   
`rememberRetained` | ✅ | ✅ | ✅ | ✅ |   
`TestEventSink` | ✅ | ✅ | ✅ | ✅ | On JS you must use `asEventSinkFunction()`.  
```

--------------------------------

### produceRetainedState Usage Example

Source: https://slackhq.github.io/circuit/api/0.x/circuit-retained/com.slack.circuit.retained/produce-retained-state

An example demonstrating how to use produceRetainedState to observe external data sources and update the UI state. It shows how to collect data from a repository and set it as the value within the producer.

```kotlin
@Composable
fun FavoritesPresenter(favoritesRepository: FavoritesRepository): State {
  val state by produceRetainedState<UiState<List<Person>>>(UiState.Loading, favoritesRepository) {
    favoritesRepository.people
      .map { UiState.Data(it) }
      .collect { value = it }
  }
  return state
}
```

--------------------------------

### OverlayTransitionController Companion API

Source: https://slackhq.github.io/circuit/api/0.x/circuit-overlay/com.slack.circuit.overlay/-overlay-transition-controller/-companion/index

Documentation for the Companion object of OverlayTransitionController, including its properties and methods. Specifically details the NoOp implementation.

```APIDOC
OverlayTransitionController:
  Companion
    Properties:
      NoOp: OverlayTransitionController
        A no-op implementation of OverlayTransitionController.
```

--------------------------------

### Produce Retained State Example

Source: https://slackhq.github.io/circuit/api/0.x/circuit-retained/com.slack.circuit.retained/produce-retained-state

An example demonstrating the usage of `produceRetainedState` to observe external data sources like a repository and update the UI state accordingly. It maps data from the repository and collects it into the `State`.

```kotlin
@Composable
fun FavoritesPresenter(favoritesRepository: FavoritesRepository): State {
  val state by produceRetainedState<UiState<List<Person>>>(UiState.Loading, favoritesRepository) {
    favoritesRepository.people
      .map { UiState.Data(it) }
      .collect { value = it }
  }
  return state
}
```

--------------------------------

### State Retention Example (Process Death Survival)

Source: https://slackhq.github.io/circuit/api/0.x/circuit-retained/com.slack.circuit.retained/remember-retained

This example shows how `rememberSaveable` can be used to retain state across configuration changes, back stack, and process death. It is suitable for primitives or implicitly saveable types.

```kotlin
@Composable
override fun present(): CounterState {
  var count by rememberSaveable { mutableStateOf(0) }

  return CounterState(count) { event ->
    when (event) {
      is CounterEvent.Increment -> state = count++
      is CounterEvent.Decrement -> state = count--
    }
  }
}
```

--------------------------------

### Circuit Runtime Screen API

Source: https://slackhq.github.io/circuit/api/0.x/circuit-foundation/com.slack.circuit.foundation/-event-listener/on-start-present

API documentation for the Circuit runtime screen components, including PopResult, Screen, and StaticScreen.

```APIDOC
PopResult:
  Represents the result of a pop operation.

Screen:
  Abstract base class for screens in Circuit.

StaticScreen:
  A screen that does not change its state.
```

--------------------------------

### AnimatedNavEvent Functions

Source: https://slackhq.github.io/circuit/api/0.x/circuit-foundation/com.slack.circuit.foundation.animation/-animated-nav-event/index

Includes functions to retrieve enum constants by name or to get all constants.

```APIDOC
AnimatedNavEvent:
  valueOf(value: String): AnimatedNavEvent
    Returns the enum constant of this type with the specified name. The string must match exactly an identifier used to declare an enum constant in this type. (Extraneous whitespace characters are not permitted.)
  values(): Array<AnimatedNavEvent>
    Returns an array containing the constants of this enum type, in the order they're declared.
```

--------------------------------

### Circuit Foundation API

Source: https://slackhq.github.io/circuit/api/0.x/circuit-overlay/com.slack.circuit.overlay/-overlay-transition-controller/-companion/-no-op

Core API documentation for the Circuit library's foundation module. Includes the main Circuit class, composition locals, and event listeners.

```APIDOC
com.slack.circuit.foundation:
  answeringNavigationAvailable()
    - Checks if answering navigation is available.
  Circuit
    - The main Circuit class for managing navigation and state.
    - Builder
      - Builder for creating a Circuit instance.
    - circuit()
      - Creates a Circuit instance.
  CircuitCompositionLocals()
    - Provides composition locals for Circuit.
  CircuitContent()
    - Composable function to display Circuit content.
  CircuitPreview()
    - Composable function for previewing Circuit content.
  ContentProviderState
    - Represents the state of a content provider.
  DelicateCircuitFoundationApi
    - Annotation for delicate APIs in the foundation module.
  EventListener
    - Interface for listening to Circuit events.
    - Companion
      - Companion object for EventListener.
    - Factory
      - Factory for creating EventListener instances.
  LocalBackStack
    - Provides the local backstack.
  LocalCircuit
    - Provides the local Circuit instance.
  LocalRecordLifecycle
    - Provides the local record lifecycle.
```

--------------------------------

### Circuit Foundation API

Source: https://slackhq.github.io/circuit/api/0.x/circuit-overlay/com.slack.circuit.overlay/-overlay-transition-controller/index

Core API documentation for the Circuit library's foundation module. Includes the main Circuit class, composition locals, and event listeners.

```APIDOC
com.slack.circuit.foundation:
  answeringNavigationAvailable()
    - Checks if answering navigation is available.
  Circuit
    - The main Circuit class for managing navigation and state.
    - Builder
      - Builder for creating a Circuit instance.
    - circuit()
      - Creates a Circuit instance.
  CircuitCompositionLocals()
    - Provides composition locals for Circuit.
  CircuitContent()
    - Composable function to display Circuit content.
  CircuitPreview()
    - Composable function for previewing Circuit content.
  ContentProviderState
    - Represents the state of a content provider.
  DelicateCircuitFoundationApi
    - Annotation for delicate APIs in the foundation module.
  EventListener
    - Interface for listening to Circuit events.
    - Companion
      - Companion object for EventListener.
    - Factory
      - Factory for creating EventListener instances.
  LocalBackStack
    - Provides the local backstack.
  LocalCircuit
    - Provides the local Circuit instance.
  LocalRecordLifecycle
    - Provides the local record lifecycle.
```

--------------------------------

### Circuit Granular Artifacts

Source: https://slackhq.github.io/circuit/setup

Lists the available artifacts in the Circuit library, their purposes, and their dependencies. This allows developers to include only the necessary components for their projects.

```markdown
Artifact ID | Dependencies  
---|---
`circuit-backstack` | Circuit’s backstack implementation.  
`circuit-runtime` | Common runtime components like `Screen`, `Navigator`, etc.  
`circuit-runtime-presenter` | The `Presenter` API, depends on `circuit-runtime`.  
`circuit-runtime-ui` | The `Ui` API, depends on `circuit-runtime`.  
`circuit-foundation` | The Circuit foundational APIs like `Circuit`, `CircuitContent`, etc. Depends on the first three.  
`circuit-test` | First-party test APIs for testing navigation, state emissions, and event sinks.  
`circuit-overlay` | Optional `Overlay` APIs.  
`circuit-retained` | Optional `rememberRetained()` APIs.
```

--------------------------------

### Circuitx Android API

Source: https://slackhq.github.io/circuit/api/0.x/circuitx/android/com.slack.circuitx.android/-android-screen-starter/start

API documentation for Circuitx Android extensions, including AndroidScreen, AndroidScreenStarter, and IntentScreen.

```APIDOC
AndroidScreen:
  A screen that can be hosted by an Android Activity.

AndroidScreenStarter:
  Starts Android screens.

IntentScreen:
  A screen that can be launched via an Android Intent.
```

--------------------------------

### Circuit Foundation API

Source: https://slackhq.github.io/circuit/api/0.x/circuitx/overlays/com.slack.circuitx.overlays/-basic-alert-dialog-overlay/-basic-alert-dialog-overlay

Core API documentation for the Circuit library's foundation module. Includes the main Circuit class, composition locals, and event listeners.

```APIDOC
com.slack.circuit.foundation:
  answeringNavigationAvailable()
    - Checks if answering navigation is available.
  Circuit
    - The main Circuit class for managing navigation and state.
    - Builder
      - Builder for creating a Circuit instance.
    - circuit()
      - Creates a Circuit instance.
  CircuitCompositionLocals()
    - Provides composition locals for Circuit.
  CircuitContent()
    - Composable function to display Circuit content.
  CircuitPreview()
    - Composable function for previewing Circuit content.
  ContentProviderState
    - Represents the state of a content provider.
  DelicateCircuitFoundationApi
    - Annotation for delicate APIs in the foundation module.
  EventListener
    - Interface for listening to Circuit events.
    - Companion
      - Companion object for EventListener.
    - Factory
      - Factory for creating EventListener instances.
  LocalBackStack
    - Provides the local backstack.
  LocalCircuit
    - Provides the local Circuit instance.
  LocalRecordLifecycle
    - Provides the local record lifecycle.
```

--------------------------------

### CircuitX Gesture Navigation API

Source: https://slackhq.github.io/circuit/api/0.x/circuit-foundation/com.slack.circuit.foundation/-event-listener/on-start-present

API documentation for CircuitX gesture navigation components.

```APIDOC
GestureNavigation:
  Provides utilities for gesture-based navigation.
```

--------------------------------

### AndroidScreenAwareNavigator Example

Source: https://slackhq.github.io/circuit/circuitx/navigation

This code snippet demonstrates how to use `rememberAndroidScreenAwareNavigator` to create a navigator that handles `AndroidScreen` subtypes, such as `IntentScreen`, by delegating to an underlying CircuitNavigator.

```kotlin
val backStack = rememberSaveableBackStack(Screen)
val baseNavigator = rememberCircuitNavigator(backStack)
val navigator = rememberAndroidScreenAwareNavigator(baseNavigator, AndroidScreenStarter())
NavigableCircuitContent(navigator = navigator, backStack = backStack)
```

--------------------------------

### Circuit Runtime Screen API

Source: https://slackhq.github.io/circuit/api/0.x/circuit-overlay/com.slack.circuit.overlay/-overlay-transition-controller/-companion/index

API documentation for the Circuit runtime screen components, including PopResult, Screen, and StaticScreen.

```APIDOC
PopResult:
  Represents the result of a pop operation.

Screen:
  Abstract base class for screens in Circuit.

StaticScreen:
  A screen that does not change its state.
```

--------------------------------

### Circuit Runtime UI API

Source: https://slackhq.github.io/circuit/api/0.x/circuit-overlay/com.slack.circuit.overlay/-overlay-state/-u-n-a-v-a-i-l-a-b-l-e/index

API documentation for the Circuit runtime UI components, including Ui and its Factory.

```APIDOC
Ui:
  Represents a UI element in the Circuit framework.
  Factory:
    A factory for creating Ui instances.
```

--------------------------------

### Circuit Runtime UI API

Source: https://slackhq.github.io/circuit/api/0.x/circuit-foundation/com.slack.circuit.foundation/-event-listener/on-start-present

API documentation for Circuit runtime UI components, focusing on the Ui interface and its factory.

```APIDOC
Ui:
  Interface for UI components.
  ui(): Function to get the UI implementation.
```

```APIDOC
Factory:
  Factory for creating Ui instances.
```

--------------------------------

### Remember Event Listener

Source: https://slackhq.github.io/circuit/api/0.x/circuit-foundation/com.slack.circuit.foundation/index

Remembers an EventListener instance for a given screen and context. It can be configured to start on initialization and accepts an optional EventListener.Factory.

```APIDOC
rememberEventListener(screen: Screen, context: CircuitContext = CircuitContext.EMPTY, startOnInit: Boolean = true, factory: EventListener.Factory? = null): EventListener
  - Remembers a new EventListener instance for the given screen and context.
  - Parameters:
    - screen: The screen for which the event listener is created.
    - context: The CircuitContext for the event listener (defaults to empty).
    - startOnInit: A boolean flag to determine if the listener should start on initialization (defaults to true).
    - factory: An optional EventListener.Factory to customize listener creation.
```

--------------------------------

### Android IntentScreen API

Source: https://slackhq.github.io/circuit/api/0.x/circuitx/android/com.slack.circuitx.android/-intent-screen/index

Documentation for the IntentScreen class in CircuitX Android. This class wraps an Android Intent and optional options for starting activities.

```APIDOC
IntentScreen:
  data class IntentScreen(val intent: Intent, val options: Bundle? = null) : AndroidScreen
  A simple Intent that wraps an intent and optional options bundle. These are passed on to Context.startActivity.

  For reuse in custom AndroidScreenStarter implementations, you can call startWith on instances of this.

  Constructors:
    IntentScreen(intent: Intent, options: Bundle? = null)

  Properties:
    intent: Intent
    options: Bundle? = null
```

--------------------------------

### Circuit Foundation API

Source: https://slackhq.github.io/circuit/api/0.x/circuit-overlay/com.slack.circuit.overlay/-local-overlay-host

Core API documentation for the Circuit library's foundation module. Includes the main Circuit class, composition locals, and event listeners.

```APIDOC
com.slack.circuit.foundation:
  answeringNavigationAvailable()
    - Checks if answering navigation is available.
  Circuit
    - The main Circuit class for managing navigation and state.
    - Builder
      - Builder for creating a Circuit instance.
    - circuit()
      - Creates a Circuit instance.
  CircuitCompositionLocals()
    - Provides composition locals for Circuit.
  CircuitContent()
    - Composable function to display Circuit content.
  CircuitPreview()
    - Composable function for previewing Circuit content.
  ContentProviderState
    - Represents the state of a content provider.
  DelicateCircuitFoundationApi
    - Annotation for delicate APIs in the foundation module.
  EventListener
    - Interface for listening to Circuit events.
    - Companion
      - Companion object for EventListener.
    - Factory
      - Factory for creating EventListener instances.
  LocalBackStack
    - Provides the local backstack.
  LocalCircuit
    - Provides the local Circuit instance.
  LocalRecordLifecycle
    - Provides the local record lifecycle.
```

--------------------------------

### Circuit Overlay API

Source: https://slackhq.github.io/circuit/api/0.x/circuit-runtime-presenter/com.slack.circuit.runtime.presenter/-presenter/-factory/create

API documentation for the Circuit overlay system. This covers various components for managing and displaying overlays, including AnimatedOverlay, ContentWithOverlays, OverlayHost, and related state and navigation utilities.

```APIDOC
AnimatedOverlay:
  Description: Represents an overlay with animation capabilities.

ContentWithOverlays(): ContentWithOverlays
  Description: Composable function to display content with overlays.
  Returns: A composable function that renders content and overlays.

LocalOverlayHost:
  Description: Provides access to the current OverlayHost in the composition.

LocalOverlayState:
  Description: Provides access to the current overlay state in the composition.

Overlay:
  Description: Represents a generic overlay.

OverlayEffect(): OverlayEffect
  Description: Represents an effect associated with an overlay.

OverlayHost:
  Description: Manages and displays overlays.

OverlayHostData:
  Description: Data associated with an OverlayHost.

OverlayNavigator:
  Description: Navigates through overlays.

OverlayScope:
  Description: Scope for overlay operations.

OverlayState:
  Description: Represents the state of an overlay.
  States:
    UNAVAILABLE: The overlay is not available.
    HIDDEN: The overlay is hidden.
    SHOWING: The overlay is currently being shown.

OverlayTransitionController:
  Description: Controls the transitions of overlays.
  Companion:
    Description: Companion object for OverlayTransitionController.

ReadOnlyOverlayApi:
  Description: Read-only API for overlay operations.

rememberOverlayHost(): OverlayHost
  Description: Creates and remembers an OverlayHost.
  Returns: The remembered OverlayHost.
```

--------------------------------

### AndroidScreen Interface

Source: https://slackhq.github.io/circuit/api/0.x/circuitx/android/com.slack.circuitx.android/-android-screen/index

Represents a Screen that refers to a start-able Android component, such as an Intent. These screens are intercepted by the Navigator and routed to an AndroidScreenStarter for native starting.

```APIDOC
AndroidScreen
interface AndroidScreen : Screen
A Screen that refers to a start-able Android component, such as an Intent.
These screens are intercepted by the intercepting Navigator returned by rememberAndroidScreenAwareNavigator and routed to an AndroidScreenStarter that can start it natively, such as via Context.startActivity.
This is an interop layer between the Navigator API and the Android platform, and not something that should be used to navigate between standard Circuit screens. It should be assumed that calling Navigator.goTo with an AndroidScreen will result in exiting the current Circuit UI.

Inheritors:
IntentScreen
```

--------------------------------

### Circuit Foundation API

Source: https://slackhq.github.io/circuit/api/0.x/circuit-overlay/com.slack.circuit.overlay/-animated-overlay/enter-transition

Core foundation APIs for the Circuit framework, including the main Circuit class, composition locals, and event listeners.

```APIDOC
com.slack.circuit.foundation:
  answeringNavigationAvailable()
    - Checks if answering navigation is available.

  Circuit
    - The main Circuit class.
    - Properties:
      - Builder: Builder for creating a Circuit instance.

  circuit()
    - Function to get the current Circuit instance.

  CircuitCompositionLocals()
    - Composable function to provide Circuit locals.

  CircuitContent()
    - Composable function to display Circuit content.

  CircuitPreview()
    - Composable function for previewing Circuit components.

  ContentProviderState
    - Represents the state of a content provider.

  DelicateCircuitFoundationApi
    - Annotation for delicate foundation APIs.

  EventListener
    - Interface for listening to Circuit events.
    - Properties:
      - Companion: Companion object for EventListener.
      - Factory: Factory for creating EventListeners.

  LocalBackStack
    - Provides the local backstack.

  LocalCircuit
    - Provides the local Circuit instance.

  LocalRecordLifecycle
    - Provides the local record lifecycle.
```

--------------------------------

### Example Usage of rememberAnsweringNavigator

Source: https://slackhq.github.io/circuit/api/0.x/circuit-foundation/com.slack.circuit.foundation/remember-answering-navigator

Demonstrates how to use rememberAnsweringNavigator to create a navigator that handles a specific result type (PickPhotoScreen.Result) and how to trigger navigation and pop with a result.

```kotlin
val pickPhotoNavigator = rememberAnsweringNavigator(backStack, PickPhotoScreen.Result::class) { result: PickPhotoScreen.Result ->
  // Do something with the result!
}

return State(...) { event ->
  when (event) {
    is PickPhoto -> pickPhotoNavigator.goTo(PickPhotoScreen)
  }
}

// In PickPhotoScreen
navigator.pop(PickPhotoScreen.Result(...))
```

--------------------------------

### CircuitX Android API

Source: https://slackhq.github.io/circuit/api/0.x/circuitx/android/com.slack.circuitx.android/-intent-screen/start-with

API documentation for CircuitX Android extensions, including AndroidScreen, AndroidScreenStarter, and IntentScreen.

```APIDOC
AndroidScreen:
  A screen that is backed by an Android Activity or Fragment.

AndroidScreenStarter:
  Starts Android screens.

IntentScreen:
  A screen that is represented by an Android Intent.
```

```APIDOC
rememberAndroidScreenAwareNavigator(): Creates a navigator aware of Android screens.
```

--------------------------------

### Circuit Runtime UI API

Source: https://slackhq.github.io/circuit/api/0.x/circuitx/overlays/com.slack.circuitx.overlays/-basic-alert-dialog-overlay/-basic-alert-dialog-overlay

API documentation for Circuit runtime UI components, focusing on the Ui interface and its factory.

```APIDOC
Ui:
  Interface for UI components.
  ui(): Function to get the UI implementation.
```

```APIDOC
Factory:
  Factory for creating Ui instances.
```

--------------------------------

### SharedElementTransitionLayout Setup

Source: https://slackhq.github.io/circuit/shared-elements

Demonstrates the correct placement of SharedElementTransitionLayout around the root Circuit content to enable overlay and navigation animated visibility scopes.

```kotlin
setContent{
CircuitCompositionLocals(circuit){
SharedElementTransitionLayout{
ContentWithOverlays{NavigableCircuitContent()}
}
}
}
```

--------------------------------

### Circuit Runtime UI API

Source: https://slackhq.github.io/circuit/api/0.x/circuit-overlay/com.slack.circuit.overlay/-overlay-transition-controller/-companion/index

API documentation for Circuit runtime UI components, focusing on the Ui interface and its factory.

```APIDOC
Ui:
  Interface for UI components.
  ui(): Function to get the UI implementation.
```

```APIDOC
Factory:
  Factory for creating Ui instances.
```

--------------------------------

### AnimatedNavDecorator updateTransition

Source: https://slackhq.github.io/circuit/api/0.x/circuit-foundation/com.slack.circuit.foundation.animation/-animated-nav-decorator/update-transition

Sets up a Transition for driving AnimatedContent used to navigate between screens. The transition should be setup from the current NavDecoration.DecoratedContent arguments, and then updated when the arguments change.

```APIDOC
AnimatedNavDecorator:
  updateTransition(args: ImmutableList<T>): Transition<S>
    Sets up a Transition for driving an AnimatedContent used to navigate between screens. The transition should be setup from the current NavDecoration.DecoratedContent arguments, and then updated when the arguments change.
```

--------------------------------

### Remember Event Listener

Source: https://slackhq.github.io/circuit/api/0.x/circuit-foundation/com.slack.circuit.foundation/remember-event-listener

Remembers a new EventListener instance for a given screen and context. Allows for automatic starting of the listener and provides a factory for customization.

```APIDOC
rememberEventListener(
    screen: Screen,
    context: CircuitContext = CircuitContext.EMPTY,
    startOnInit: Boolean = true,
    factory: EventListener.Factory? = null
): EventListener

Parameters:
  screen: The Screen for which to remember the EventListener.
  context: The CircuitContext to associate with the EventListener.
  startOnInit: Indicates whether to call EventListener.start() automatically after instantiation. Defaults to true.
  factory: An optional factory to create the EventListener.
```

--------------------------------

### Creating a Backstack and Navigator

Source: https://slackhq.github.io/circuit/tutorial

Demonstrates how to create a saveable backstack and a navigator for managing app navigation. The navigator handles actions when the root screen is popped.

```kotlin
val backStack = rememberSaveableBackStack(root = InboxScreen)
val navigator = rememberCircuitNavigator(backStack) {
    // Do something when the root screen is popped, usually exiting the app
}
```

--------------------------------

### Circuit Foundation API

Source: https://slackhq.github.io/circuit/api/0.x/circuit-runtime-ui/com.slack.circuit.runtime.ui/-ui/-factory/create

Core API documentation for the Circuit library's foundation module. Includes the main Circuit class, composition locals, and event listeners.

```APIDOC
com.slack.circuit.foundation:
  answeringNavigationAvailable()
    - Checks if answering navigation is available.
  Circuit
    - The main Circuit class for managing navigation and state.
    - Builder
      - Builder for creating a Circuit instance.
    - circuit()
      - Creates a Circuit instance.
  CircuitCompositionLocals()
    - Provides composition locals for Circuit.
  CircuitContent()
    - Composable function to display Circuit content.
  CircuitPreview()
    - Composable function for previewing Circuit content.
  ContentProviderState
    - Represents the state of a content provider.
  DelicateCircuitFoundationApi
    - Annotation for delicate APIs in the foundation module.
  EventListener
    - Interface for listening to Circuit events.
    - Companion
      - Companion object for EventListener.
    - Factory
      - Factory for creating EventListener instances.
  LocalBackStack
    - Provides the local backstack.
  LocalCircuit
    - Provides the local Circuit instance.
  LocalRecordLifecycle
    - Provides the local record lifecycle.
```

--------------------------------

### Circuit Documentation Updates

Source: https://slackhq.github.io/circuit/changelog

Includes fixes for variable casing in Navigation documentation examples and adds a note to the tutorial about creating a presenter only for supported screen types.

```kotlin
// [docs] Fix variable casing in Navigation documentation example.
// Add note about only creating a presenter for supported screen types in tutorial.
```

--------------------------------

### Circuit Presenter Code Generation (Class)

Source: https://slackhq.github.io/circuit/code-gen

Example of annotating a Presenter class with `@CircuitInject` to generate its corresponding `Presenter.Factory`. The generated factory is contributed via `@ContributesMultibinding`.

```kotlin
@CircuitInject(HomeScreen::class,AppScope::class)
classHomePresenter@Inject constructor(...):Presenter<HomeState>{...}

// Generates
@ContributesMultibinding(AppScope::class)
classHomePresenterFactory@Inject constructor():Presenter.Factory{...}
```

--------------------------------

### CircuitX Android API

Source: https://slackhq.github.io/circuit/api/0.x/circuit-foundation/com.slack.circuit.foundation/-event-listener/on-start-present

API documentation for CircuitX Android extensions, including AndroidScreen, AndroidScreenStarter, and IntentScreen.

```APIDOC
AndroidScreen:
  A screen that is backed by an Android Activity or Fragment.

AndroidScreenStarter:
  Starts Android screens.

IntentScreen:
  A screen that is represented by an Android Intent.
```

```APIDOC
rememberAndroidScreenAwareNavigator(): Creates a navigator aware of Android screens.
```

--------------------------------

### Circuit Runtime Screen API

Source: https://slackhq.github.io/circuit/api/0.x/circuit-overlay/com.slack.circuit.overlay/-overlay-transition-controller/index

API documentation for the Circuit runtime screen components, including Screen, PopResult, and StaticScreen.

```APIDOC
Screen:
  Represents a screen in the Circuit navigation.

PopResult:
  Represents the result of a pop operation from the navigation stack.

StaticScreen:
  A screen that does not change its state.
```

--------------------------------

### Circuit UI Code Generation (Class)

Source: https://slackhq.github.io/circuit/code-gen

Example of annotating a UI class with `@CircuitInject` to generate its corresponding `Ui.Factory`. The generated factory is contributed via `@ContributesMultibinding`.

```kotlin
@CircuitInject(HomeScreen::class,AppScope::class)
classHomeUi@Inject constructor(...):Ui<HomeState>{...}

// Generates
@ContributesMultibinding(AppScope::class)
classHomeUiFactory@Inject constructor():Ui.Factory{...}
```
Tokens:
Raw