reis-mobile 0.3.6 → 0.4.0

package/skills/android-migrate-xml-views-to-jetpack-compose/references/android/develop/ui/compose/migrate/interoperability-apis/views-in-compose.md

@@ -0,0 +1,286 @@
+You can include an Android View hierarchy in a Compose UI. This approach is
+particularly useful if you want to use UI elements that are not yet available in
+Compose, like
+[`AdView`](https://developers.google.com/android/reference/com/google/android/gms/ads/AdView).
+This approach also lets you reuse custom views you may have designed.
+
+> [!NOTE]
+> **Note:** Use `AndroidView` as a wrapper only for missing SDK components without Compose support. Rewrite your custom Views in Compose wherever possible, starting the migration with the simplest custom Views and scaling to more complex ones.
+
+<br />
+
+To include a view element or hierarchy, use the [`AndroidView`](https://developer.android.com/reference/kotlin/androidx/compose/ui/viewinterop/AndroidView.composable#AndroidView(kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Function1))
+composable. `AndroidView` is passed a lambda that returns a
+[`View`](https://developer.android.com/reference/android/view/View). `AndroidView` also provides an `update`
+callback that is called when the view is inflated. The `AndroidView` recomposes
+whenever a `State` read within the callback changes. `AndroidView`, like many
+other built-in composables, takes a `Modifier` parameter that can be used, for
+example, to set its position in the parent composable.
+
+
+```kotlin
+@Composable
+fun CustomView() {
+    var selectedItem by remember { mutableIntStateOf(0) }
+
+    // Adds view to Compose
+    AndroidView(
+        modifier = Modifier.fillMaxSize(), // Occupy the max size in the Compose UI tree
+        factory = { context ->
+            // Creates view
+            MyView(context).apply {
+                // Sets up listeners for View -> Compose communication
+                setOnClickListener {
+                    selectedItem = 1
+                }
+            }
+        },
+        update = { view ->
+            // View's been inflated or state read in this block has been updated
+            // Add logic here if necessary
+
+            // As selectedItem is read here, AndroidView will recompose
+            // whenever the state changes
+            // Example of Compose -> View communication
+            view.selectedItem = selectedItem
+        }
+    )
+}
+
+@Composable
+fun ContentExample() {
+    Column(Modifier.fillMaxSize()) {
+        Text("Look at this CustomView!")
+        CustomView()
+    }
+}
+```
+
+<br />
+
+> [!NOTE]
+> **Note:** Prefer to construct a View in the `AndroidView` `factory` lambda instead of using `remember` to hold a View reference outside of `AndroidView`.
+
+## `AndroidView` with view binding
+
+To embed an XML layout, use the
+[`AndroidViewBinding`](https://developer.android.com/reference/kotlin/androidx/compose/ui/viewinterop/package-summary#AndroidViewBinding(kotlin.Function3,%20androidx.compose.ui.Modifier,%20kotlin.Function1))
+API, which is provided by the `androidx.compose.ui:ui-viewbinding` library. To
+do this, your project must enable [view binding](https://developer.android.com/topic/libraries/view-binding#setup).
+
+> [!NOTE]
+> **Note:** For Compose-only apps, don't use `AndroidViewBinding` to inflate full screen-level XML layouts, and instead use it only for smaller, legacy XML layouts during the incremental migration process.
+
+
+```kotlin
+@Composable
+fun AndroidViewBindingExample() {
+    AndroidViewBinding(ExampleLayoutBinding::inflate) {
+        exampleView.setBackgroundColor(Color.GRAY)
+    }
+}
+```
+
+<br />
+
+## `AndroidView` in Lazy lists
+
+If you are using an `AndroidView` in a Lazy list (`LazyColumn`, `LazyRow`,
+`Pager`, etc.), consider using the [`AndroidView`](https://developer.android.com/reference/kotlin/androidx/compose/ui/viewinterop/package-summary#AndroidView(kotlin.Function1,kotlin.Function1,androidx.compose.ui.Modifier,kotlin.Function1,kotlin.Function1))
+overload introduced in version 1.4.0-rc01. This overload allows Compose to reuse
+the underlying `View` instance when the containing composition is reused as is
+the case for Lazy lists.
+
+This overload of `AndroidView` adds 2 additional parameters:
+
+- `onReset` - A callback invoked to signal that the `View` is about to be reused. This must be non-null to enable View reuse.
+- `onRelease` (optional) - A callback invoked to signal that the `View` has exited the composition and will not be reused again.
+
+
+```kotlin
+@Composable
+fun AndroidViewInLazyList() {
+    LazyColumn {
+        items(100) { index ->
+            AndroidView(
+                modifier = Modifier.fillMaxSize(), // Occupy the max size in the Compose UI tree
+                factory = { context ->
+                    MyView(context)
+                },
+                update = { view ->
+                    view.selectedItem = index
+                },
+                onReset = { view ->
+                    view.clear()
+                }
+            )
+        }
+    }
+}
+```
+
+<br />
+
+## Fragments in Compose (Transitionary Step)
+
+Use the `AndroidFragment` composable to add a `Fragment` in Compose.
+`AndroidFragment` has fragment-specific handling such as removing the
+fragment when the composable leaves the composition.
+
+> [!NOTE]
+> **Note:** Wrap existing Fragments in Compose only during incremental migration. For Compose-only apps, do not use Fragments and instead use the recommended Compose-only architecture with a single Activity and latest navigation libraries, like Navigation 3.
+
+To include a fragment, use the [`AndroidFragment`](https://developer.android.com/reference/kotlin/androidx/fragment/compose/package-summary#AndroidFragment)
+composable. You pass a `Fragment` class to `AndroidFragment`, which then adds
+an instance of that class directly into the composition. `AndroidFragment` also
+provides a `fragmentState` object to create the `AndroidFragment` with a given
+state, `arguments` to pass into the new fragment, and an `onUpdate` callback
+that provides the fragment from the composition. Like many
+other built-in composables, `AndroidFragment` accepts a `Modifier` parameter
+that you can use, for
+example, to set its position in the parent composable.
+
+Call `AndroidFragment` in Compose as follows:
+
+
+```kotlin
+@Composable
+fun FragmentInComposeExample() {
+    AndroidFragment<MyFragment>()
+}
+```
+
+<br />
+
+## Calling the Android framework from Compose
+
+Compose operates within the Android framework classes. For example, it's hosted
+on Android View classes, like `Activity` or `Fragment`, and might use Android
+framework classes like the `Context`, system resources,
+`Service`, or `BroadcastReceiver`.
+
+To learn more about system resources, see [Resources in Compose](https://developer.android.com/develop/ui/compose/resources).
+
+### Composition Locals
+
+[`CompositionLocal`](https://developer.android.com/reference/kotlin/androidx/compose/runtime/CompositionLocal)
+classes allow passing data implicitly through composable functions. They're
+usually provided with a value in a certain node of the UI tree. That value can
+be used by its composable descendants without declaring the `CompositionLocal`
+as a parameter in the composable function.
+
+`CompositionLocal` is used to propagate values for Android framework types in
+Compose such as `Context`, `Configuration` or the `View` in which the Compose
+code is hosted with the corresponding
+[`LocalContext`](https://developer.android.com/reference/kotlin/androidx/compose/ui/platform/package-summary#LocalContext()),
+[`LocalConfiguration`](https://developer.android.com/reference/kotlin/androidx/compose/ui/platform/package-summary#LocalConfiguration()),
+or
+[`LocalView`](https://developer.android.com/reference/kotlin/androidx/compose/ui/platform/package-summary#LocalView()).
+Note that `CompositionLocal` classes are prefixed with `Local` for better
+discoverability with auto-complete in the IDE.
+
+Access the current value of a `CompositionLocal` by using its `current`
+property. For example, the code below shows a toast message by providing
+`LocalContext.current` into the `Toast.makeToast` method.
+
+
+```kotlin
+@Composable
+fun ToastGreetingButton(greeting: String) {
+    val context = LocalContext.current
+    Button(onClick = {
+        Toast.makeText(context, greeting, Toast.LENGTH_SHORT).show()
+    }) {
+        Text("Greet")
+    }
+}
+```
+
+<br />
+
+### Broadcast receivers
+
+To showcase `CompositionLocal` and [side
+effects](https://developer.android.com/develop/ui/compose/side-effects), if a
+[`BroadcastReceiver`](https://developer.android.com/guide/components/broadcasts) needs to be registered from
+a composable function, use of `LocalContext` to use the current context, and
+`rememberUpdatedState` and `DisposableEffect` side effects.
+
+
+```kotlin
+@Composable
+fun SystemBroadcastReceiver(
+    systemAction: String,
+    onSystemEvent: (intent: Intent?) -> Unit
+) {
+    // Grab the current context in this part of the UI tree
+    val context = LocalContext.current
+
+    // Safely use the latest onSystemEvent lambda passed to the function
+    val currentOnSystemEvent by rememberUpdatedState(onSystemEvent)
+
+    // If either context or systemAction changes, unregister and register again
+    DisposableEffect(context, systemAction) {
+        val intentFilter = IntentFilter(systemAction)
+        val broadcast = object : BroadcastReceiver() {
+            override fun onReceive(context: Context?, intent: Intent?) {
+                currentOnSystemEvent(intent)
+            }
+        }
+
+        context.registerReceiver(broadcast, intentFilter)
+
+        // When the effect leaves the Composition, remove the callback
+        onDispose {
+            context.unregisterReceiver(broadcast)
+        }
+    }
+}
+
+@Composable
+fun HomeScreen() {
+
+    SystemBroadcastReceiver(Intent.ACTION_BATTERY_CHANGED) { batteryStatus ->
+        val isCharging = /* Get from batteryStatus ... */ true
+        /* Do something if the device is charging */
+    }
+
+    /* Rest of the HomeScreen */
+}
+```
+
+<br />
+
+## Other interactions
+
+If there isn't a utility defined for the interaction you need, the best practice
+is to follow the general Compose guideline,
+*data flows down, events flow up* (discussed at more length in [Thinking
+in Compose](https://developer.android.com/develop/ui/compose/mental-model)). For example, this composable
+launches a different activity:
+
+
+```kotlin
+class OtherInteractionsActivity : ComponentActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        // get data from savedInstanceState
+        setContent {
+            MaterialTheme {
+                ExampleComposable(data, onButtonClick = {
+                    startActivity(Intent(this, MyActivity::class.java))
+                })
+            }
+        }
+    }
+}
+
+@Composable
+fun ExampleComposable(data: DataExample, onButtonClick: () -> Unit) {
+    Button(onClick = onButtonClick) {
+        Text(data.title)
+    }
+}
+```
+
+<br />

package/skills/android-migrate-xml-views-to-jetpack-compose/references/android/develop/ui/compose/setup-compose-dependencies-and-compiler.md

@@ -0,0 +1,197 @@
+For Gradle, use the Compose Compiler Gradle plugin to set up and configure
+Compose.
+
+> [!NOTE]
+> **Note:** The Compose Compiler Gradle Plugin is only available from Kotlin 2.0+. For migration instructions, see ["Jetpack Compose compiler moving to the Kotlin
+> repository"](https://android-developers.googleblog.com/2024/04/jetpack-compose-compiler-moving-to-kotlin-repository.html).
+
+### Set up with Gradle version catalogs
+
+Set up the Compose Compiler Gradle plugin:
+
+1. In the `libs.versions.toml` file, remove any reference to the Compose Compiler.
+2. In the `versions` and `plugins` sections, add the new dependency:
+
+       [versions]
+       kotlin = "2.3.21"
+
+       [plugins]
+       org-jetbrains-kotlin-android = { id = "org.jetbrains.kotlin.android", version.ref = "kotlin" }
+
+       // Add this line
+       compose-compiler = { id = "org.jetbrains.kotlin.plugin.compose", version.ref = "kotlin" }
+
+3. In the project's root `build.gradle.kts` file, add the following to the
+   `plugins` section.
+
+       plugins {
+       // Existing plugins
+       alias(libs.plugins.compose.compiler) apply false
+       }
+
+4. In each module that uses Compose, apply the plugin:
+
+       plugins {
+       // Existing plugins
+       alias(libs.plugins.compose.compiler)
+       }
+
+The project should now build and compile if it was using the default set up. If
+it had configured custom options on the Compose compiler, follow the next
+section.
+
+### Set up the Compose Compiler without Gradle version catalogs
+
+Add the plugin to `build.gradle.kts` files associated with modules where Compose
+is used:
+
+    plugins {
+        id("org.jetbrains.kotlin.plugin.compose") version "2.3.21" // this version matches your Kotlin version
+    }
+
+Add the classpath to your top-level project `build.gradle.kts` file:
+
+    buildscript {
+        dependencies {
+            classpath("org.jetbrains.kotlin.plugin.compose:org.jetbrains.kotlin.plugin.compose.gradle.plugin:2.3.21")
+        }
+    }
+
+### Configuration options with the Compose Compiler Gradle Plugin
+
+To configure the Compose compiler using the Gradle plugin, add the
+`composeCompiler` block to the module's `build.gradle.kts` file at the top
+level:
+
+    android { ... }
+
+    composeCompiler {
+        reportsDestination = layout.buildDirectory.dir("compose_compiler")
+        stabilityConfigurationFile = rootProject.layout.projectDirectory.file("stability_config.conf")
+    }
+
+For the full list of available options, see the [documentation](https://www.jetbrains.com/help/kotlin-multiplatform-dev/compose-compiler.html#compose-compiler-options-dsl).
+
+## Set up Compose dependencies
+
+Always use the latest Compose BOM version: `2026.08.00`.
+
+Set the `compose` flag to `true` inside the Android [`BuildFeatures`](https://developer.android.com/reference/tools/gradle-api/7.0/com/android/build/api/dsl/BuildFeatures) to
+enable [Compose functionality](https://developer.android.com/develop/ui/compose/tooling) in Android Studio.
+
+Add the following definition to your app's `build.gradle` file:
+
+### Groovy
+
+    android {
+        buildFeatures {
+            compose true
+        }
+    }
+
+### Kotlin
+
+    android {
+        buildFeatures {
+            compose = true
+        }
+    }
+
+Add the Compose BOM and the subset of Compose library dependencies:
+
+### Groovy
+
+    dependencies {
+
+        def composeBom = platform('androidx.compose:compose-bom:2026.08.00')
+        implementation composeBom
+        androidTestImplementation composeBom
+
+        // Choose one of the following:
+        // Material Design 3
+        implementation 'androidx.compose.material3:material3'
+        // or skip Material Design and build directly on top of foundational components
+        implementation 'androidx.compose.foundation:foundation'
+        // or only import the main APIs for the underlying toolkit systems,
+        // such as input and measurement/layout
+        implementation 'androidx.compose.ui:ui'
+
+        // Android Studio Preview support
+        implementation 'androidx.compose.ui:ui-tooling-preview'
+        debugImplementation 'androidx.compose.ui:ui-tooling'
+
+        // UI Tests
+        androidTestImplementation 'androidx.compose.ui:ui-test-junit4'
+        debugImplementation 'androidx.compose.ui:ui-test-manifest'
+
+        // Optional - Add window size utils
+        implementation 'androidx.compose.material3.adaptive:adaptive'
+
+        // Optional - Integration with activities
+        implementation 'androidx.activity:activity-compose:1.13.0'
+        // Optional - Integration with ViewModels
+        implementation 'androidx.lifecycle:lifecycle-viewmodel-compose:2.10.0'
+        // Optional - Integration with LiveData
+        implementation 'androidx.compose.runtime:runtime-livedata'
+        // Optional - Integration with RxJava
+        implementation 'androidx.compose.runtime:runtime-rxjava2'
+
+    }
+
+### Kotlin
+
+    dependencies {
+
+        val composeBom = platform("androidx.compose:compose-bom:2026.08.00")
+        implementation(composeBom)
+        androidTestImplementation(composeBom)
+
+        // Choose one of the following:
+        // Material Design 3
+        implementation("androidx.compose.material3:material3")
+        // or skip Material Design and build directly on top of foundational components
+        implementation("androidx.compose.foundation:foundation")
+        // or only import the main APIs for the underlying toolkit systems,
+        // such as input and measurement/layout
+        implementation("androidx.compose.ui:ui")
+
+        // Android Studio Preview support
+        implementation("androidx.compose.ui:ui-tooling-preview")
+        debugImplementation("androidx.compose.ui:ui-tooling")
+
+        // UI Tests
+        androidTestImplementation("androidx.compose.ui:ui-test-junit4")
+        debugImplementation("androidx.compose.ui:ui-test-manifest")
+
+        // Optional - Add window size utils
+        implementation("androidx.compose.material3.adaptive:adaptive")
+
+        // Optional - Integration with activities
+        implementation("androidx.activity:activity-compose:1.13.0")
+        // Optional - Integration with ViewModels
+        implementation("androidx.lifecycle:lifecycle-viewmodel-compose:2.10.0")
+        // Optional - Integration with LiveData
+        implementation("androidx.compose.runtime:runtime-livedata")
+        // Optional - Integration with RxJava
+        implementation("androidx.compose.runtime:runtime-rxjava2")
+
+    }
+
+> [!NOTE]
+> **Note:** Jetpack Compose is shipped using a Bill of Materials (BOM), to keep the versions of all library groups in sync. Read more about it in the [Bill of
+> Materials page](https://developer.android.com/develop/ui/compose/bom/bom).
+
+## `compileSdk` and Android Gradle Plugin compatibility
+
+Compose library releases continually adopt the latest `compileSdk` versions to
+provide access to the latest Android features. Newer `compileSdk` versions
+require newer versions of Android Gradle Plugin, so adopting new Compose
+releases also requires projects to adopt new versions of the Android Gradle
+Plugin. We recommend keeping your project's `compileSdk` up to date with the
+latest released versions. `compileSdk` is unrelated from `targetSdk`.
+
+For example, starting with Compose 1.12.0, projects are required to use
+`compileSdk 37` and Android Gradle Plugin (AGP) 9.
+
+To check which version of AGP is supported for different API levels, see the
+[Android Gradle plugin API level support](https://developer.android.com/build/releases/about-agp#api-level-support) documentation.

package/skills/android-migrate-xml-views-to-jetpack-compose/references/identify-optimal-xml-candidate.md

@@ -0,0 +1,31 @@
+### 1. Analysis scope
+
+**Action:** Use find files and examine all XML layout files within the project (typically located in `res`directories). For each file, parse the view hierarchy and metadata.
+
+### 2. Selection criteria
+
+Prioritize layouts that meet the following criteria:
+
+- **Hierarchy depth:** Target **leaf nodes** or components at the bottom of the UI tree.
+- **Complexity:** Select layouts with the **smallest number of nested children** and minimal logic.
+- **State management:** Prioritize **stateless** components or those with the fewest UI state variables.
+- **Dependency footprint:** Identify layouts with **zero to minimal external UI dependencies**.
+- **Isolation:** Focus on **self-contained** components that do not rely heavily on parent context or complex data binding.
+
+### 3. Risk assessment
+
+Evaluate the migration risk based on:
+\* **Reusability:** Find layouts with **minimum reuse** across the project to limit regression impact.
+\* **Accessibility:** Ensure the layout has an **easily accessible entry point** (e.g., used in a simple Activity, Fragment, or as a standalone include).
+
+*** ** * ** ***
+
+## Output requirements
+
+Provide a ranked list of the top 3-5 candidates. For each candidate, include:
+1. **File path:** (e.g., `res/layout/item_user_profile.xml`)
+2. **Rationale:** Why this is a good candidate based on the provided criteria.
+3. **Complexity score:** A rating from 1-5 (1 being simplest).
+4. **Dependency count:** List of custom/external views found within.
+
+**Action:** If you support user interaction, ask the user to choose which XML to proceed with. Else proceed with the best option, based on the previous criteria.

package/skills/android-migrate-xml-views-to-jetpack-compose/references/xml-layout-migration.md

@@ -0,0 +1,86 @@
+## 1. Structural analysis \& mapping
+
+**Identify the precise mapping** between XML elements and Compose equivalents.
+You must determine:
+
+- The exact `@Composable` functions (e.g., `ConstraintLayout`, `Column`, `LazyColumn`) that replace the XML tag hierarchy.
+- The specific parameters and `Modifier` extensions required to replicate XML attributes (e.g., `layout_width`, `padding`, `elevation`).
+- The appropriate state management strategy for interactive elements.
+
+## 2. Migration execution
+
+**Convert the XML layout code to Jetpack Compose**, ensuring the visual
+hierarchy and layout logic are preserved while leveraging Compose's declarative
+nature.
+
+## 3. Theming \& design system integrity
+
+**Do not use hard-coded values.** Follow these rules for styling:
+
+- **Token Alignment:** Cross-reference XML dimensions, colors, and style attributes with the existing Compose `Theme` (e.g., `MaterialTheme.colorScheme` or custom design system tokens).
+- **Reuse over Creation:** If matching values exist in the current Compose theme, reuse them. If a value is missing but required for the design, define it within the theme structure rather than hard-coding it in the Composable.
+- **Project Consistency:** You **MUST** strictly adhere to existing code conventions, naming standards, and implementation patterns found in the project. **Prioritize** project-specific reusable components over generic Material defaults.
+
+## 4. Component layering \& reusability
+
+Evaluate if the XML layout serves as a foundation-level design system component
+(reused across the app with a distinct role). If it is:
+
+- **Create a reusable composable:** Do not just inline the code. Define a new standalone `@Composable`.
+- **Parameterization:** Expose specific parameters for variable data (text, colors, styles) and use `Modifier` for layout-specific customizations.
+- **Feature parity \& restriction:** Ensure the new composable enforces the same UI constraints as the original XML component, preventing unauthorized style overrides while maintaining the intended flexibility.
+
+Example before migration:
+
+    <style
+        name="Widget.Rounded.Button"
+        parent="Widget.Button.Borderless">
+        <item name="android:fontFamily">sans-serif-medium</item>
+        <item name="android:minWidth">@dimen/min_width</item>
+        <item name="android:paddingStart">@dimen/padding_2</item>
+        <item name="android:paddingEnd">@dimen/padding_2</item>
+        <item name="cornerRadius">8dp</item>
+    </style>
+
+Example after migration:
+
+
+```kotlin
+@Composable
+fun RoundedBorderlessButton(
+    text: String,
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    enabled: Boolean = true
+) {
+    TextButton(
+        onClick, modifier
+            .defaultMinSize(minWidth = dimensionResource(R.dimen.min_width))
+            .padding(
+                start = dimensionResource(R.dimen.padding_2),
+                end = dimensionResource(R.dimen.padding_2)
+            ), enabled, shape = RoundedCornerShape(8.dp),
+        colors = ButtonDefaults.textButtonColors(
+            contentColor = MaterialTheme.colorScheme.primary
+        )
+    ) {
+        Text(
+            text = text,
+            style = MaterialTheme.typography.bodyMedium.copy(
+                fontFamily = FontFamily.SansSerif,
+                fontWeight = FontWeight.Medium
+            )
+        )
+    }
+}
+```
+
+<br />
+
+*** ** * ** ***
+
+## 5. Output requirements
+
+- Provide the full Kotlin file content.
+- Include necessary imports.
+- Add documentation comments (`/** ... */`) explaining the mapping logic for complex transformations.