reis-mobile 0.3.6 → 0.4.0

package/skills/android-navigation-event/references/android/guide/navigation/navigation-event/dispatcher.md

@@ -0,0 +1,134 @@
+To implement a robust navigation system, your app needs a centralized way to
+handle back gestures and other navigation signals. This page describes how to
+use [`NavigationEventDispatcher`](https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher) to coordinate and distribute these
+navigation events across your application.
+
+## Declare a `NavigationEventDispatcher`
+
+The `NavigationEventDispatcher` is the central component of the
+`NavigationEvent` library. It acts as an event hub that dispatches
+navigation-related events, such as back gestures and navigation transitions, to
+registered listeners within your app. Components can subscribe to these events
+to react to navigation changes or other system-driven navigation actions.
+
+You should provide `NavigationEventDispatcher` instances through a
+[`NavigationEventDispatcherOwner`](https://developer.android.com/reference/androidx/navigationevent/NavigationEventDispatcherOwner). This ensures that different parts of your
+app can access the same dispatcher and observe navigation events in a consistent
+and coordinated way.
+
+
+```kotlin
+class MyComponent: NavigationEventDispatcherOwner {
+    override val navigationEventDispatcher: NavigationEventDispatcher =
+        NavigationEventDispatcher()
+}
+```
+
+<br />
+
+If you are inside of a `ComponentActivity`, instead of implementing your own
+dispatcher, you can retrieve the one provided for you.
+
+
+```kotlin
+class MyCustomActivity : ComponentActivity() {
+    fun addMyHandler() {
+        // navigationEventDispatcher provided by the ComponentActivity
+        navigationEventDispatcher.addHandler(myNavigationEventHandler)
+    }
+}
+```
+
+<br />
+
+## Add a `NavigationEventInput`
+
+Now that you've registered the handler, you are set up to receive events.
+However, you need to provide a source from which the events are generated with
+`NavigationEventInput`.
+
+`NavigationEventInput` is the platform-specific component that receives
+raw system input and translates it into a standard `NavigationEvent` to be sent
+to the `NavigationEventDispatcher`.
+
+The following example is a custom implementation of a `NavigationEventInput`:
+
+
+```kotlin
+public class MyInput : NavigationEventInput() {
+    @MainThread
+    public fun backStarted(event: NavigationEvent) {
+        dispatchOnBackStarted(event)
+    }
+
+    @MainThread
+    public fun backProgressed(event: NavigationEvent) {
+        dispatchOnBackProgressed(event)
+    }
+
+    @MainThread
+    public fun backCancelled() {
+        dispatchOnBackCancelled()
+    }
+
+    @MainThread
+    public fun backCompleted() {
+        dispatchOnBackCompleted()
+    }
+}
+```
+
+<br />
+
+Next, provide that input to your dispatcher:
+
+
+```kotlin
+navigationEventDispatcher.addInput(MyInput())
+```
+
+<br />
+
+> [!NOTE]
+> **Note:** To provide a simple input, use the [`DirectNavigationEventInput`](https://developer.android.com/reference/androidx/navigationevent/DirectNavigationEventInput) class.
+
+## Clean up resources with `dispose()`
+
+To prevent memory leaks in a dynamic UI, every created
+`NavigationEventDispatcher` instance must be explicitly removed from the
+hierarchy using the `dispose()` method when the component it is tied to is
+destroyed:
+
+
+```kotlin
+navigationEventDispatcher.dispose()
+```
+
+<br />
+
+The `dispose()` method ensures a *cascading cleanup* by iteratively removing
+the dispatcher and all of its descendants (children and grandchildren),
+guaranteeing that all associated handlers are unregistered from the shared
+system.
+
+### Dispatcher hierarchy and control
+
+The `NavigationEventDispatcher` supports a parent-child hierarchy, enabling
+components nested deep within a UI (such as nested `NavHost`s or dialogs) to
+participate in navigation event handling.
+
+#### Create a child dispatcher
+
+A child dispatcher is created by passing a reference to its parent dispatcher
+during construction. All dispatchers in a hierarchy share the same
+`NavigationEventProcessor` to maintain a global **Last-In, First-Out (LIFO)**
+event ordering based on priority.
+
+#### Hierarchical enabling
+
+The dispatcher includes an `isEnabled` property that allows developers to enable
+or disable an entire subtree of handlers at once.
+
+When a parent dispatcher is disabled (`isEnabled = false`), all handlers
+associated with that parent and any of its children will be ignored, regardless
+of their individual enabled state.

package/skills/android-navigation-event/references/android/guide/navigation/navigation-event/handle-back.md

@@ -0,0 +1,217 @@
+You can extend the abstract class `NavigationEventHandler` to handle navigation
+events across platforms. This class provides methods corresponding to the
+lifecycle of a navigation gesture.
+
+
+```kotlin
+val myHandler = object: NavigationEventHandler<NavigationEventInfo>(
+    initialInfo = NavigationEventInfo.None,
+    isBackEnabled = true
+) {
+    override fun onBackStarted(event: NavigationEvent) {
+        // Prepare for the back event
+    }
+
+    override fun onBackProgressed(event: NavigationEvent) {
+        // Use event.progress for predictive animations
+    }
+
+    // This is the required method for final event handling
+    override fun onBackCompleted() {
+        // Complete the back event
+    }
+
+    override fun onBackCancelled() {
+        // Cancel the back event
+    }
+}
+```
+
+<br />
+
+The `addHandler` function connects the handler to the dispatcher:
+
+
+```kotlin
+navigationEventDispatcher.addHandler(myHandler)
+```
+
+<br />
+
+Call `myHandler.remove()` to remove the handler from the dispatcher:
+
+
+```kotlin
+myHandler.remove()
+```
+
+<br />
+
+Handlers are invoked based on priority, and then by recency. All
+[`PRIORITY_OVERLAY`](https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#PRIORITY_OVERLAY()) handlers are called before any [`PRIORITY_DEFAULT`](https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher#PRIORITY_DEFAULT())
+handlers. Within each priority group, handlers are invoked in a Last-In,
+First-Out (LIFO) order --- the most recently added handler is called first.
+
+## Intercept back with Jetpack Compose
+
+For Jetpack Compose, the library provides a utility composable to manage the
+dispatcher hierarchy.
+
+The `NavigationBackHandler` composable creates a `NavigationEventHandler` for
+its content and links it to the `LocalNavigationEventDispatcherOwner`. It uses
+Compose's `DisposableEffect` to automatically call the dispatcher's `dispose()`
+method when the composable leaves the screen, safely managing resources.
+
+
+```kotlin
+@Composable
+public fun NavigationBackHandler(
+    state: NavigationEventState<out NavigationEventInfo>,
+    isBackEnabled: Boolean = true,
+    onBackCancelled: () -> Unit = {},
+    onBackCompleted: () -> Unit,
+){
+
+}
+```
+
+<br />
+
+This function lets you control event handling precisely within localized UI
+subtrees.
+
+
+```kotlin
+@Composable
+fun HandlingBackWithTransitionState(
+    onNavigateUp: () -> Unit
+) {
+    val navigationState = rememberNavigationEventState(
+        currentInfo = NavigationEventInfo.None
+    )
+    val transitionState = navigationState.transitionState
+    // React to predictive back transition updates
+    when (transitionState) {
+        is NavigationEventTransitionState.InProgress -> {
+            val progress = transitionState.latestEvent.progress
+            // Use progress (0f..1f) to update UI during the gesture
+        }
+        is NavigationEventTransitionState.Idle -> {
+            // Reset any temporary UI state if the gesture is cancelled
+        }
+    }
+    NavigationBackHandler(
+        state = navigationState,
+        onBackCancelled = {
+            // Called if the back gesture is cancelled
+        },
+        onBackCompleted = {
+            // Called when the back gesture fully completes
+            onNavigateUp()
+        }
+    )
+}
+```
+
+<br />
+
+This example shows how to observe predictive back gesture updates using
+[`NavigationEventTransitionState`](https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventTransitionState). The `progress` value can be used to
+update UI elements in response to the back gesture, while handling completion
+and cancellation through `NavigationBackHandler`.
+
+### Access the back gesture or swipe edge in Compose
+
+> [!NOTE]
+> **Note:** For Android, if you're already using a navigation library with built-in Predictive Back support, like [Navigation 3](https://developer.android.com/guide/navigation/navigation-3/animate-destinations), use that instead of implementing the guidance here. The following section shows how to create a Predictive Back animation using only `NavigationEvent` and Compose.
+
+**Figure 1** . A predictive back animation built with `NavigationEvent` and Compose.
+
+To animate the screen while the user swipes back, you'll need to (a) check if
+the `NavigationEventTransitionState` is `InProgress`, and (b) observe the
+progress and swipe edge state with `rememberNavigationEventState`:
+
+- `progress`: A Float from `0.0` to `1.0` indicating how far the user has swiped.
+- `swipeEdge`: An integer constant (`EDGE_LEFT` or `EDGE_RIGHT`) indicating where the gesture started.
+
+The following snippet is a simplified example of how to implement a scale and
+shift animation:
+
+
+```kotlin
+object Routes {
+    const val SCREEN_A = "Screen A"
+    const val SCREEN_B = "Screen B"
+}
+
+class MainActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContent {
+            var state by remember { mutableStateOf(Routes.SCREEN_A) }
+            val backEventState = rememberNavigationEventState<NavigationEventInfo>(currentInfo = NavigationEventInfo.None)
+            when (state) {
+                Routes.SCREEN_A -> {
+                    ScreenA(onNavigate = { state = Routes.SCREEN_B })
+                }
+                else -> {
+                    if (backEventState.transitionState is NavigationEventTransitionState.InProgress) {
+                        ScreenA(onNavigate = { })
+                    }
+                    ScreenB(
+                        backEventState = backEventState,
+                        onBackCompleted = { state = Routes.SCREEN_A }
+                    )
+                }
+            }
+        }
+    }
+}
+
+@Composable
+fun ScreenB(
+    backEventState: NavigationEventState<NavigationEventInfo>,
+    onBackCompleted: () -> Unit = {},
+) {
+    val transitionState = backEventState.transitionState
+    val latestEvent =
+        (transitionState as? NavigationEventTransitionState.InProgress)
+            ?.latestEvent
+    val backProgress = latestEvent?.progress ?: 0f
+    val swipeEdge = latestEvent?.swipeEdge ?: NavigationEvent.EDGE_LEFT
+    if (transitionState is NavigationEventTransitionState.InProgress) {
+        Log.d("BackGesture", "Progress: ${transitionState.latestEvent.progress}")
+    } else if (transitionState is NavigationEventTransitionState.Idle) {
+        Log.d("BackGesture", "Idle")
+    }
+    val animatedScale by animateFloatAsState(
+        targetValue = 1f - (backProgress * 0.1f),
+        label = "ScaleAnimation"
+    )
+    val windowInfo = LocalWindowInfo.current
+    val density = LocalDensity.current
+    val maxShift = remember(windowInfo, density) {
+        val widthDp = with(density) { windowInfo.containerSize.width.toDp() }
+        (widthDp.value / 20f) - 8
+    }
+    val offsetX = when (swipeEdge) {
+        NavigationEvent.EDGE_LEFT -> (backProgress * maxShift).dp
+        NavigationEvent.EDGE_RIGHT -> (-backProgress * maxShift).dp
+        else -> 0.dp
+    }
+    NavigationBackHandler(
+        state = backEventState,
+        onBackCompleted = onBackCompleted,
+        isBackEnabled = true
+    )
+    Box(
+        modifier = Modifier
+            .offset(x = offsetX)
+            .scale(animatedScale)
+    ){
+        // Rest of UI
+    }
+}
+```
+
+<br />

package/skills/android-navigation-event/references/android/guide/navigation/navigation-event/index.md

@@ -0,0 +1,83 @@
+Navigation Event is a library that provides a Kotlin Multiplatform (KMP)
+solution for integrating system-level navigation events into your application.
+It is designed to be the foundational layer for handling navigation directions
+across various [supported platforms](https://developer.android.com/kotlin/multiplatform#kotlin-multiplatform-and-jetpack-libraries).
+
+## Key concepts
+
+The Navigation Event system is built around a centralized dispatcher-handler
+model, often used in a parent-child hierarchy to map to complex UI structures,
+such as those found in Jetpack Compose.
+
+### `NavigationEventDispatcher`
+
+The [`NavigationEventDispatcher`](https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventDispatcher) is the central class responsible for
+managing all registered navigation event consumers
+([`NavigationEventHandler`](https://developer.android.com/reference/kotlin/androidx/navigationevent/NavigationEventHandler))) and orchestrating the flow of events.
+
+In a hierarchical setup, all dispatchers within the same chain share a single
+`NavigationEventProcessor`, which manages the global state and ensures a single,
+unified dispatching order across the entire tree.
+
+### `NavigationEventHandler`
+
+`NavigationEventHandler` is an abstract class that receives and handles
+navigation events dispatched by a `NavigationEventDispatcher`. It defines
+callback methods that correspond to different stages of a navigation gesture
+lifecycle, such as when a gesture starts, progresses, completes, or is
+cancelled.
+
+Handlers can respond to these events to update UI or application state in
+response to user navigation actions. Multiple handlers can be registered with a
+dispatcher and are invoked based on priority and registration order.
+
+### `NavigationEvent`
+
+[`NavigationEvent`](https://developer.android.com/reference/androidx/navigationevent/NavigationEvent) is a data class that carries the details of the
+navigation gesture.
+
+### `NavigationEventInfo`
+
+[`NavigationEventInfo`](https://developer.android.com/reference/androidx/navigationevent/NavigationEventInfo) is an abstract class that provides contextual
+information about a navigation state.
+
+### `NavigationEventInput`
+
+[`NavigationEventInput`](https://developer.android.com/reference/androidx/navigationevent/NavigationEventInput) is an abstract class for components that generate
+and dispatch navigation events. It acts as the "input" side of the navigation
+system, translating platform-specific events (like system back gestures or
+button clicks) into standardized events that can be sent to a
+`NavigationEventDispatcher`.
+
+## Supported navigation directions and triggers
+
+The Navigation Event system is designed to encompass more than just the system
+back button, with designs supporting multiple navigation directions and input
+methods across platforms.
+
+### Supported directions
+
+Different platforms support varying navigation directions:
+
+|---|---|---|---|---|
+| **Platform** | **Back** | **Up** | **Forward** | **Home** |
+| **Android phone** | ✅ | ✅ | 🚫 | ✅ |
+| **Android tablet** | ✅ | ✅ | 🚫 | ✅ |
+| **Web (Browser)** | ✅ | ✅ | ✅ | 🚫 |
+| **iOS (iPhone/iPad)** | ✅ | 🚫 | ✅ | ✅ |
+
+### Supported triggers
+
+Input handling is achieved through various mechanisms on each platform:
+
+|---|---|---|---|
+| **Trigger** | **Android Phone** | **Web (Browser)** | **iOS (iPhone/iPad)** |
+| **Keyboard back button** | ✅ Back | ❓ | ✅ Back |
+| **Software back button** | 🚫 | ✅ Back | ✅ Back |
+| **Software up button** | ✅ Up | 🚫 | 🚫 |
+| **Gesture from left** | ✅ Back | ❓ | ✅ Back |
+| **Gesture from right** | ✅ Back | ❓ | ✅ Forward |
+| **Gesture from bottom** | ✅ Home | 🚫 | ✅ Home |
+
+> [!NOTE]
+> **Note:** The **Web** platform has unique navigation handling, where the browser controls the back stack state. This requires synchronization between the browser window and the application's navigation stack. The question mark represents behavior that is inconsistent because web browsers don't have a single, unified "back" button or gesture.

package/skills/android-navigation-event/references/android/guide/navigation/navigation-event/setup.md

@@ -0,0 +1,32 @@
+To set up your development environment for `NavigationEvent`, follow these
+steps.
+
+## Declare dependencies
+
+1. Add the `navigationevent` artifact to your project. This is the core library
+   containing the shared `NavigationEventDispatcher` and `NavigationEventHandler`
+   classes.
+
+   For Jetpack Compose integration, you also need to add the corresponding
+   Compose artifact:
+
+       [versions]
+       navigationevent = "1.0.0"
+
+       [libraries]
+       # NavigationEvent libraries
+       androidx-navigationevent = { module = "androidx.navigationevent:navigationevent", version.ref = "navigationevent" }
+       androidx-navigationevent-compose = { module = "androidx.navigationevent:navigationevent-compose", version.ref = "navigationevent" }
+
+2. Update your compile SDK to 36 or above:
+
+       [versions]
+       compileSdk = "36"
+
+3. Add the following to your app build file, `app/build.gradle.kts`:
+
+       dependencies {
+         ...
+         implementation(libs.androidx.navigationevent)
+         implementation(libs.androidx.navigationevent.compose)
+       }

package/skills/android-play-billing-library-version-upgrade/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: android-play-billing-library-version-upgrade
+description: Use this skill when upgrading or migrating an Android project from any
+  legacy Google Play Billing Library (PBL) version to the latest stable version of
+  PBL.
+license: Apache-2.0
+source: https://github.com/android/skills
+routing: manual
+stacks: [android]
+metadata:
+  author: Google LLC
+  last-updated: '2026-09-01'
+  keywords:
+  - android
+  - play billing
+  - play billing library
+  - pbl
+  - upgrade
+  - migration
+  - deprecation
+  - google play
+---
+
+## Phase 0: Intent Message
+
+**Reporting Action**: Before proceeding, immediately tell the user: "I will
+upgrade Play Billing Library to the latest version."
+
+## Phase 1: Discovery \& Situational Awareness
+
+1. **Primary Check (Build Version)** : Locate the project's billing dependency (e.g., `com.android.billingclient:billing`) in `build.gradle`, `build.gradle.kts`, or `libs.versions.toml`.
+2. **Initial Compilation Test**: Attempt to sync and build the project immediately.
+3. **Fallback Discovery (Effective Version)** :
+   - **Trigger**: Only if the build fails immediately, scan the source code for deprecated artifacts.
+   - **Logic** : The presence of deprecated APIs indicates the **"Effective
+     Version"** ---defined as the version where those specific APIs were **last
+     available**, not when they were introduced.
+   - **Example** : If `SkuDetails` is present, treat the baseline as **PBL v7** or earlier (regardless of the version string in `build.gradle`).
+4. **Identify Target \& Path** : Access the version tool or release notes to find the latest stable version and calculate a \[Direct/Stepped\] migration path based on the **Effective Version** baseline.
+
+- **Calculate Migration Path** :
+  - If the **Effective Version** is within 2 major versions of the target: Plan a **Direct Migration**.
+  - If it is more than 2 major versions behind: Plan a **Stepped
+    Migration**. Migrate by two major versions at a time (e.g., v4 -\> v6 -\> v8) until you are within two versions of the target.
+- **Reporting Action**: Before proceeding, tell the user: "I've detected you are effectively on PBL \[Current\] and the latest is \[Target\]. I am planning a \[direct/stepped\] migration path."
+
+## Phase 2: Contextual Document Mapping \& Planning
+
+For every major version jump identified in your path, you **MUST** synthesize
+instructions from:
+
+- **[Migration Guide](https://developer.android.com/google/play/billing/migrate-gpblv%5BX%5D)** (where `[X]` is the target major version).
+- **Release Highlights** : The "Deprecations" and "Breaking Changes" sections of the relevant [Release Notes](references/android/google/play/billing/release-notes.md).
+- **Developer Documentation**: Consult your knowledge of the Google Play Billing documentation regarding the relevant features used in this app (e.g., Subscriptions, One-Time Products).
+- **Develop the Plan**: Identify every specific code change required (API removals, class replacements, logic shifts) and print this out as a checklist.
+
+## Phase 3: Instructions for Execution
+
+*Reporting Action: For each of the following steps, give a brief explanation of
+what you will be doing prior to execution, and a brief summary of what you
+accomplished afterwards.*
+
+### Step 1: SDK \& Environment Alignment
+
+- **Action** : Update `build.gradle` to meet SDK requirements (e.g., "PBL 9 requires `compileSdk` 35").
+- **Gradle Version**: Verify if the new library requires a newer Android Gradle Plugin (AGP) or Kotlin version.
+
+### Step 2: Intent-based Refactoring
+
+Analyze the intent of the existing code rather than performing purely textual
+string replacement.
+
+- **Action** : You **MUST** follow all deprecation instructions and refactor patterns from **both** the [references/migration-logic.md](references/migration-logic.md) section, the official migration guides, and the general documentation pages identified in Phase 2.
+- **Verification** : Verify you are doing **all steps from all documentation** and then making sure you follow the specific directions from the checklist in the references.
+
+### Step 3: Sequential Verification (Only applicable for Stepped Migrations)
+
+1. **Upgrade** to the first major intermediate version in your path.
+2. **Run `./gradlew assembleDebug`** to verify no intermediate breaking changes were missed.
+3. **Repeat** until you reach the final target version.
+
+### Step 4: Final Validation Checklist
+
+1. **Smart Checklist Verification**:
+2. Open [references/version-checklist.md](references/version-checklist.md) and locate the **Smart Version-Specific Checklist**.
+3. **Action**: For every version between your \[Detected Effective Version\] and \[Detected New Version\], verify that every item has been addressed in the code using "Find in Files" or structural analysis.
+4. **Tests** : Run all unit and implementation tests (`./gradlew test`).
+5. **Clean Build** : Verify the project completes a full clean build: `./gradlew clean assembleDebug`. Then, run `./gradlew sync` and `./gradlew build` so that the user can immediately test the new version manually.
+
+## Final Report
+
+Explain the "Why" to the developer:
+
+- "I updated your SDK to \[Version\] because PBL \[Version\] requires it for \[Reason from docs\]."
+- "I removed your custom `retryConnection()` logic because it is now handled natively by the library using `enableAutoServiceReconnection()`."
+- "Successfully upgraded from PBL \[Old\] to PBL \[New\] and verified with unit tests. Based on an analysis of features in the latest library and this application's current feature set, I suggest exploring \[New Feature\] (e.g., Prepaid Plans or Installments) from the latest release because it is now available but not yet implemented."