@devo-bmad-custom/agent-orchestration 1.0.0

package/src/.agents/skills/ui-ux-pro-custom/data/jetpack-compose-expert-skill/references/deprecated-patterns.md

@@ -0,0 +1,323 @@
+# Deprecated Patterns & API Migrations in Jetpack Compose
+
+This guide covers major API changes and deprecations in Compose's evolution. Each section shows the old pattern → new approach with migration notes.
+
+---
+
+## String-Based Routes → Type-Safe `@Serializable` Routes
+
+**Old (pre-2.8):**
+```kotlin
+NavHost(navController, startDestination = "home") {
+    composable("home") { HomeScreen() }
+    composable("details/{id}") { backStackEntry ->
+        DetailsScreen(id = backStackEntry.arguments?.getString("id"))
+    }
+}
+```
+
+**New (Navigation 2.8+):**
+```kotlin
+@Serializable data class Home
+@Serializable data class Details(val id: String)
+
+NavHost(navController, startDestination = Home) {
+    composable<Home> { HomeScreen() }
+    composable<Details> { backStackEntry ->
+        val args: Details = backStackEntry.toRoute()
+        DetailsScreen(id = args.id)
+    }
+}
+```
+
+**Migration notes:** Type-safe routes eliminate string typos and runtime crashes. Requires `kotlinx-serialization` plugin and `navigation-compose:2.8.0+`. Encode complex objects using custom serializers.
+
+---
+
+## `accompanist-systemuicontroller` → `enableEdgeToEdge()`
+
+**Old:**
+```kotlin
+val systemUiController = rememberSystemUiController()
+systemUiController.setSystemBarsColor(
+    color = Color.Transparent,
+    darkIcons = false
+)
+```
+
+**New (Compose 1.7+):**
+```kotlin
+enableEdgeToEdge()
+// In Activity.onCreate() before setContent {}
+```
+
+**Migration notes:** Built-in since Compose 1.7. Automatically handles status bar, navigation bar, and IME behind content. Remove `accompanist-systemuicontroller` dependency entirely.
+
+---
+
+## `accompanist-permissions` → `activity-compose`
+
+**Old:**
+```kotlin
+val permissionState = rememberPermissionState(android.Manifest.permission.CAMERA)
+```
+
+**New:**
+```kotlin
+val permissionState = rememberPermissionState(android.Manifest.permission.CAMERA) {
+    // callback when permission changes
+}
+```
+
+**Migration notes:** Functionality moved to `androidx.activity:activity-compose`. The API is largely identical; main change is dependency update. For multiple permissions, use `rememberMultiplePermissionsState()`.
+
+---
+
+## `accompanist-pager` → `HorizontalPager`/`VerticalPager`
+
+**Old:**
+```kotlin
+val pagerState = rememberPagerState()
+HorizontalPager(count = items.size, state = pagerState) { page ->
+    PageContent(items[page])
+}
+```
+
+**New (Foundation):**
+```kotlin
+val pagerState = rememberPagerState(pageCount = { items.size })
+HorizontalPager(state = pagerState) { page ->
+    PageContent(items[page])
+}
+```
+
+**Migration notes:** Native Pager in `foundation:1.6+` replaces accompanist. Removes external dependency. State initialization slightly different; pass lambda for dynamic page counts.
+
+---
+
+## `accompanist-swiperefresh` → `PullToRefreshBox`
+
+**Old:**
+```kotlin
+SwipeRefresh(state = rememberSwipeRefreshState(isRefreshing), onRefresh = { load() }) {
+    LazyColumn { items(data) { item -> ItemRow(item) } }
+}
+```
+
+**New (Material3):**
+```kotlin
+PullToRefreshBox(isRefreshing = isRefreshing, onRefresh = { load() }) {
+    LazyColumn { items(data) { item -> ItemRow(item) } }
+}
+```
+
+**Migration notes:** `PullToRefreshBox` in `material3:1.2+` is the official replacement. Cleaner API. Remove `accompanist-swiperefresh` dependency.
+
+---
+
+## `accompanist-flowlayout` → `FlowRow`/`FlowColumn`
+
+**Old:**
+```kotlin
+FlowRow(mainAxisSize = SizeMode.Expand) {
+    items.forEach { item -> Chip(text = item) }
+}
+```
+
+**New (Foundation):**
+```kotlin
+FlowRow(modifier = Modifier.fillMaxWidth()) {
+    items.forEach { item -> Chip(text = item) }
+}
+```
+
+**Migration notes:** FlowRow/FlowColumn in `foundation:1.6+`. API simplified; use standard modifiers instead of `SizeMode`. Better performance and less memory overhead.
+
+---
+
+## `LazyColumn { animateItemPlacement() }` → `LazyColumn { animateItem() }`
+
+**Old:**
+```kotlin
+LazyColumn {
+    items(items, key = { it.id }) { item ->
+        ItemRow(item.name, Modifier.animateItemPlacement())
+    }
+}
+```
+
+**New:**
+```kotlin
+LazyColumn {
+    items(items, key = { it.id }) { item ->
+        ItemRow(item.name, Modifier.animateItem())
+    }
+}
+```
+
+**Migration notes:** `animateItem()` is the modern API (Compose 1.7+). Returns animation state for finer control. `animateItemPlacement()` still works but is superseded.
+
+---
+
+## `Modifier.composed` Pattern → `Modifier.Node` API
+
+**Old:**
+```kotlin
+fun Modifier.myModifier(value: Int) = composed {
+    val state = remember { mutableStateOf(value) }
+    Modifier.fillMaxWidth().padding(8.dp)
+}
+```
+
+**New:**
+```kotlin
+fun Modifier.myModifier(value: Int) = this.then(
+    Modifier
+        .fillMaxWidth()
+        .padding(8.dp)
+)
+// Or for complex state:
+class MyModifierNode(val value: Int) : ModifierNodeElement<MyNodeImpl>() {
+    override fun create() = MyNodeImpl(value)
+    override fun update(node: MyNodeImpl) { node.value = value }
+}
+private class MyNodeImpl(var value: Int) : Modifier.Node
+```
+
+**Migration notes:** `composed {}` incurs overhead; avoid if no `remember` calls needed. For stateful modifiers, prefer `ModifierNode` API (Compose 1.8+). Benchmark before migrating existing code.
+
+---
+
+## Primitive State Optimization: `mutableStateOf(0)` → `mutableIntStateOf(0)`
+
+**Old:**
+```kotlin
+var count by remember { mutableStateOf(0) }
+var temperature by remember { mutableStateOf(37.5f) }
+```
+
+**New:**
+```kotlin
+var count by remember { mutableIntStateOf(0) }
+var temperature by remember { mutableFloatStateOf(37.5f) }
+```
+
+**Migration notes:** Primitive-specific functions (`mutableIntStateOf`, `mutableFloatStateOf`, `mutableLongStateOf`) avoid boxing. Negligible performance impact in UI code but best practice since Compose 1.4+.
+
+---
+
+## `collectAsState()` → `collectAsStateWithLifecycle()`
+
+**Old:**
+```kotlin
+val state by viewModel.uiState.collectAsState()
+```
+
+**New:**
+```kotlin
+val state by viewModel.uiState.collectAsStateWithLifecycle()
+```
+
+**Migration notes:** `collectAsStateWithLifecycle()` (Compose 1.6+) respects lifecycle—automatically stops collecting when activity is paused. Prevents memory leaks and redundant work. Requires `androidx.lifecycle:lifecycle-runtime-compose`.
+
+---
+
+## `@ExperimentalMaterial3Api` Graduation
+
+**Old:**
+```kotlin
+@OptIn(ExperimentalMaterial3Api::class)
+fun MyScreen() {
+    DatePicker(state = rememberDatePickerState())
+}
+```
+
+**New (Compose 1.8+, Material3 1.3+):**
+```kotlin
+fun MyScreen() {
+    DatePicker(state = rememberDatePickerState())
+}
+```
+
+**Migration notes:** DatePicker, TimePicker, ExposedDropdownMenuBox, and SearchBar graduated to stable in Material3 1.3+. Remove `@OptIn` annotations. APIs are stable—safe for production use.
+
+---
+
+## `Scaffold` Padding Enforcement
+
+**Old (problematic):**
+```kotlin
+Scaffold(topBar = { TopAppBar() }) {
+    LazyColumn { items(data) { item -> ItemRow(item) } }
+}
+```
+
+**New (required since 1.6+):**
+```kotlin
+Scaffold(topBar = { TopAppBar() }) { innerPadding ->
+    LazyColumn(modifier = Modifier.padding(innerPadding)) {
+        items(data) { item -> ItemRow(item) }
+    }
+}
+```
+
+**Migration notes:** Must use `innerPadding` parameter since Compose 1.6. Ignoring it causes content overlap under system bars. The compiler enforces this now—old pattern won't compile.
+
+---
+
+## Material 2 → Material 3 Migration
+
+**Old (Material):**
+```kotlin
+Button(onClick = { }) { Text("Click") }
+TextField(value = text, onValueChange = { text = it })
+Surface(color = MaterialTheme.colors.primary) { /* */ }
+```
+
+**New (Material3):**
+```kotlin
+Button(onClick = { }) { Text("Click") }  // Same signature
+TextField(value = text, onValueChange = { text = it })  // Same signature
+Surface(color = MaterialTheme.colorScheme.primary) { /* */ }
+```
+
+**Migration notes:** Most Composables are API-compatible. Main changes: `colors` → `colorScheme`, new shape system, updated ripple defaults. Use Compose BOM to align Material3 versions.
+
+---
+
+## `WindowInsets` & Edge-to-Edge
+
+**Old:**
+```kotlin
+Surface(modifier = Modifier.systemBarsPadding()) { /* */ }
+```
+
+**New (API 35+ default edge-to-edge):**
+```kotlin
+Surface(modifier = Modifier.padding(WindowInsets.systemBars.asPaddingValues())) { /* */ }
+// Or use enableEdgeToEdge() in Activity—handles automatically
+```
+
+**Migration notes:** Edge-to-edge is default on Android 15+. System bar colors are managed by `enableEdgeToEdge()`. Use `WindowInsets.safeDrawing` for notch-aware layouts. Deprecate manual `systemBarsPadding()` calls.
+
+---
+
+## `ObservableState` Pattern Changes
+
+**Old:**
+```kotlin
+@Composable
+fun observe(state: ObservableState): State<T> = produceState(state.value) {
+    state.onChange { value = it }
+}
+```
+
+**New:**
+```kotlin
+@Composable
+fun <T> ObservableState<T>.asState(): State<T> = produceState(this.value) {
+    snapshotFlow { value }.collect { value = it }
+}
+```
+
+**Migration notes:** `snapshotFlow {}` is preferred over direct listeners (Compose 1.6+). Integrates better with Compose's snapshot system. Use `distinctUntilChanged()` to avoid redundant recompositions.

package/src/.agents/skills/ui-ux-pro-custom/data/jetpack-compose-expert-skill/references/lists-scrolling.md

@@ -0,0 +1,400 @@
+# Lists and Scrolling in Jetpack Compose
+
+Efficient list rendering and scrolling are core to responsive mobile UIs. Jetpack Compose provides lazy layouts that compose items on-demand, not all at once.
+
+## LazyColumn and LazyRow
+
+These composables only compose visible items, making them efficient for large lists unlike `Column`/`Row` which compose all children upfront.
+
+### LazyColumn (Vertical Scrolling)
+```kotlin
+LazyColumn(modifier = Modifier.fillMaxSize()) {
+  item {
+    HeaderComposable()
+  }
+  items(itemList.size) { index ->
+    ListItemComposable(itemList[index])
+  }
+  item {
+    FooterComposable()
+  }
+}
+```
+
+### LazyRow (Horizontal Scrolling)
+```kotlin
+LazyRow(modifier = Modifier.fillMaxWidth()) {
+  items(imageList.size) { index ->
+    Image(
+      painter = painterResource(imageList[index]),
+      contentDescription = null,
+      modifier = Modifier.width(200.dp)
+    )
+  }
+}
+```
+
+**Key difference from Column/Row:** Items are composed lazily as they enter the viewport, reducing memory and CPU usage.
+
+**Source:** `androidx/compose/foundation/foundation/src/commonMain/kotlin/androidx/compose/foundation/lazy/`
+
+## DSL Patterns: item, items, itemsIndexed
+
+### `item` — Single Composable
+```kotlin
+LazyColumn {
+  item {
+    HeaderComposable()
+  }
+}
+```
+
+### `items` — From a List or Count
+```kotlin
+// From a List
+val users = listOf(User("Alice"), User("Bob"))
+LazyColumn {
+  items(users) { user ->
+    UserCard(user)
+  }
+}
+
+// From a count
+LazyColumn {
+  items(100) { index ->
+    Text("Item $index")
+  }
+}
+```
+
+### `itemsIndexed` — With Index
+```kotlin
+LazyColumn {
+  itemsIndexed(users) { index, user ->
+    Text("${index + 1}. ${user.name}")
+  }
+}
+```
+
+## Keys: Critical for Correctness and Performance
+
+The `key` parameter ensures Compose can correctly identify and reuse items even if the list is reordered.
+
+### ✓ Good: Stable Keys
+```kotlin
+data class User(val id: Long, val name: String)
+
+LazyColumn {
+  items(users, key = { it.id }) { user ->
+    UserCard(user)
+  }
+}
+```
+
+When `users` list is reordered, Compose knows which item moved because the key (id) is stable.
+
+### ✗ Bad: Index as Key
+```kotlin
+// AVOID: If list is reordered, state gets mixed up
+LazyColumn {
+  items(users, key = { index }) { user -> // Wrong!
+    var selected by remember { mutableStateOf(false) }
+    UserCard(user, selected)
+  }
+}
+```
+
+If you remove item at index 0, the item that was at index 1 moves to index 0 and incorrectly inherits the state.
+
+### ✗ Bad: No Key
+```kotlin
+// If list changes, item state/animations may misbehave
+LazyColumn {
+  items(users) { user ->
+    UserCard(user)
+  }
+}
+```
+
+Without a key, Compose can't distinguish items reliably if the list changes.
+
+**Rule:** Always provide a stable, unique key when the list can change. Use IDs, not indices.
+
+## Content Types for Recycling Optimization
+
+Use `contentType` to enable layout reuse when rendering different item types:
+
+```kotlin
+sealed class ListItem
+data class HeaderItem(val title: String) : ListItem()
+data class UserItem(val user: User) : ListItem()
+
+LazyColumn {
+  items(
+    items = listItems,
+    key = { it.id },
+    contentType = { when (it) {
+      is HeaderItem -> "header"
+      is UserItem -> "user"
+    }}
+  ) { item ->
+    when (item) {
+      is HeaderItem -> HeaderComposable(item)
+      is UserItem -> UserCard(item)
+    }
+  }
+}
+```
+
+Items with the same `contentType` can reuse layout state, improving performance when types repeat.
+
+## LazyListState: Scroll Position and Animations
+
+Manage scroll position programmatically:
+
+```kotlin
+val listState = rememberLazyListState()
+
+LazyColumn(state = listState) {
+  items(100) { index ->
+    Text("Item $index")
+  }
+}
+
+// Scroll to item 50
+LaunchedEffect(Unit) {
+  listState.scrollToItem(50)
+}
+
+// Animate scroll
+LaunchedEffect(Unit) {
+  listState.animateScrollToItem(50)
+}
+
+// Read current scroll position
+val firstVisibleIndex = listState.firstVisibleItemIndex
+val firstVisibleOffset = listState.firstVisibleItemScrollOffset
+```
+
+**Use case:** Scroll to a newly added item, or scroll on user action.
+
+## LazyVerticalGrid and LazyHorizontalGrid
+
+### Fixed Columns
+```kotlin
+LazyVerticalGrid(columns = GridCells.Fixed(3)) {
+  items(itemList.size) { index ->
+    GridItemComposable(itemList[index])
+  }
+}
+```
+
+### Adaptive Columns (Responsive)
+```kotlin
+// Column width ~100dp, fills available space with as many columns as fit
+LazyVerticalGrid(columns = GridCells.Adaptive(100.dp)) {
+  items(itemList.size) { index ->
+    GridItemComposable(itemList[index])
+  }
+}
+```
+
+Adaptive is preferable for responsive layouts.
+
+## LazyVerticalStaggeredGrid
+
+For Pinterest-style layouts with variable heights:
+
+```kotlin
+LazyVerticalStaggeredGrid(
+  columns = StaggeredGridCells.Fixed(2),
+  modifier = Modifier.fillMaxSize()
+) {
+  items(images.size) { index ->
+    AsyncImage(
+      model = images[index].url,
+      contentDescription = null,
+      modifier = Modifier.fillMaxWidth()
+    )
+  }
+}
+```
+
+Items flow into the column with the shortest current height, creating a natural staggered appearance.
+
+## HorizontalPager and VerticalPager
+
+Page-by-page horizontal or vertical swiping:
+
+```kotlin
+val pagerState = rememberPagerState(pageCount = { pages.size })
+
+HorizontalPager(state = pagerState) { page ->
+  PageComposable(pages[page])
+}
+
+// Programmatic scroll to page
+LaunchedEffect(Unit) {
+  pagerState.scrollToPage(2)
+}
+
+// Animate to page
+LaunchedEffect(Unit) {
+  pagerState.animateScrollToPage(2)
+}
+```
+
+## Sticky Headers in Lazy Lists
+
+Headers that remain visible at the top while scrolling:
+
+```kotlin
+LazyColumn {
+  stickyHeader {
+    SectionHeaderComposable("Section A")
+  }
+  items(itemsA) { item ->
+    ItemComposable(item)
+  }
+
+  stickyHeader {
+    SectionHeaderComposable("Section B")
+  }
+  items(itemsB) { item ->
+    ItemComposable(item)
+  }
+}
+```
+
+## Nested Scrolling: Pitfalls
+
+### ✗ Avoid Scrollable Inside LazyColumn
+```kotlin
+// Bad: nested scroll behavior is unpredictable
+LazyColumn {
+  item {
+    LazyRow { // Nested lazy is OK, but...
+      items(innerList) { item ->
+        InnerItem(item)
+      }
+    }
+  }
+}
+```
+
+Nested lazy composables are acceptable but require careful thought about scroll precedence.
+
+### ✗ Avoid verticalScroll Modifier Inside LazyColumn
+```kotlin
+// Bad: two scroll containers fight for input
+LazyColumn {
+  item {
+    Column(modifier = Modifier.verticalScroll(rememberScrollState())) {
+      Text("This is scrollable twice!")
+    }
+  }
+}
+```
+
+Don't wrap lazy children in scrollable modifiers; use nested lazy composables if you need multiple scroll axes.
+
+### ✓ Use nestedScroll for Complex Scenarios
+```kotlin
+val scrollState = rememberScrollState()
+val nestedScrollConnection = remember {
+  object : NestedScrollConnection {
+    override fun onPreScroll(available: Offset, source: NestedScrollSource): Offset {
+      // Custom scroll handling
+      return Offset.Zero
+    }
+  }
+}
+
+LazyColumn(modifier = Modifier.nestedScroll(nestedScrollConnection)) {
+  items(100) { index ->
+    Text("Item $index")
+  }
+}
+```
+
+## Performance: Scroll-Dependent UI
+
+### ✗ Bad: Heavy Computation in Item Lambda
+```kotlin
+LazyColumn {
+  items(users) { user ->
+    val processedData = expensiveComputation(user) // Runs every recomposition!
+    UserCard(user, processedData)
+  }
+}
+```
+
+### ✓ Good: Use derivedStateOf for Scroll-Dependent Logic
+```kotlin
+val listState = rememberLazyListState()
+val showScrollToTop = remember {
+  derivedStateOf { listState.firstVisibleItemIndex > 0 }
+}
+
+LazyColumn(state = listState) {
+  items(100) { index ->
+    Text("Item $index")
+  }
+}
+
+if (showScrollToTop.value) {
+  Button(onClick = { /* scroll up */ }) { Text("Top") }
+}
+```
+
+`derivedStateOf` derives a new value when scroll state changes without recomposing the entire list.
+
+## Anti-Patterns
+
+### ✗ Using LazyColumn for Small Fixed Lists
+```kotlin
+// Bad: overkill for 5 items
+LazyColumn {
+  items(5) { index ->
+    Text("Item $index")
+  }
+}
+```
+
+**Better:** Use `Column` for small fixed lists.
+
+### ✗ No Keys + List Mutations
+```kotlin
+var items by remember { mutableStateOf(initialList) }
+LazyColumn {
+  items(items) { item -> // No key!
+    ItemComposable(item, onDelete = {
+      items = items.filter { it.id != item.id }
+    })
+  }
+}
+```
+
+Without keys, removing an item corrupts the state of remaining items.
+
+### ✗ Creating New Objects in Keys
+```kotlin
+// Bad: key creates new object each recomposition
+LazyColumn {
+  items(users, key = { User(it.id, it.name) }) { user ->
+    UserCard(user)
+  }
+}
+```
+
+**Better:** Use primitive stable identifiers.
+
+## Key Takeaways
+
+1. Always provide stable, unique keys when using `items` on mutable lists
+2. Use `contentType` for multi-type lists to enable layout reuse
+3. Prefer `GridCells.Adaptive` for responsive grid layouts
+4. Avoid nested scrollables; use `nestedScroll` for complex scroll behavior
+5. Use `derivedStateOf` to avoid recomposing the entire list for scroll-dependent logic
+6. `LazyColumn`/`LazyRow` are for large or unbounded lists; use `Column`/`Row` for small fixed lists
+7. Never use indices as keys; list mutations will corrupt item state