AANavigationStateMachine

State machine managing Android Auto screen navigation transitions.

This class provides centralized control over screen navigation, ensuring:

• Only valid transitions are allowed

• State changes are tracked and observable

• Invalid transitions are logged with helpful error messages

• Navigation history can be queried

Design Goals

1. Predictability: All valid transitions are explicitly defined

2. Debuggability: Invalid transitions are logged with context

3. Observability: State changes are exposed via StateFlow

4. Testability: Pure state machine logic, no side effects

Valid Transitions

Integration with ScreenManager

This state machine is intentionally decoupled from ScreenManager. The caller is responsible for:

1. Calling transition to request a state change

2. Checking the result

3. Performing the actual screen push/pop based on the result

This separation allows:

• Unit testing the state machine in isolation

• Custom screen management strategies

• Validation before expensive operations

Custom Transitions

Clients can extend the state machine with additional transitions for custom screens via the additionalTransitions constructor parameter. Additional transitions are merged with the built-in defaults. If a collision is detected (same from-state and action), the built-in transition takes precedence and a warning is logged.

val customTransitions = mapOf(
    Pair(AANavigationState.RoutePreview, AANavigationAction.Custom("OpenPayment"))
        to AANavigationState.Custom("Payment"),
    Pair(AANavigationState.Custom("Payment"), AANavigationAction.Back)
        to AANavigationState.RoutePreview
)
val stateMachine = AANavigationStateMachine(additionalTransitions = customTransitions)

Parameters

See also