theus-cli 0.2.83 → 0.2.84

package/vendor/theus-arsenal/skills/patrones-compose-multiplatform/SKILL.md

@@ -1,298 +0,0 @@
----
-name: patrones-compose-multiplatform
-description: Patrones de Compose Multiplatform y Jetpack Compose para proyectos KMP — gestión de estado, navegación, theming, rendimiento y UI específica por plataforma.
----
-
-# Patrones de Compose Multiplatform
-
-Patrones para construir UI compartida en Android, iOS, escritorio y web con Compose Multiplatform y Jetpack Compose. Cubre gestión de estado, navegación, theming y rendimiento.
-
-## Cuándo activarla
-
-- Al construir UI con Compose (Jetpack Compose o Compose Multiplatform)
-- Al gestionar estado de UI con ViewModels y estado de Compose
-- Al implementar navegación en proyectos KMP o Android
-- Al diseñar composables reutilizables y sistemas de diseño
-- Al optimizar la recomposición y el rendimiento de renderizado
-
-## Gestión de estado
-
-### ViewModel + objeto de estado único
-
-Usa una sola data class para el estado de la pantalla. Exponla como `StateFlow` y recógela en Compose:
-
-```kotlin
-data class ItemListState(
-    val items: List<Item> = emptyList(),
-    val isLoading: Boolean = false,
-    val error: String? = null,
-    val searchQuery: String = ""
-)
-
-class ItemListViewModel(
-    private val getItems: GetItemsUseCase
-) : ViewModel() {
-    private val _state = MutableStateFlow(ItemListState())
-    val state: StateFlow<ItemListState> = _state.asStateFlow()
-
-    fun onSearch(query: String) {
-        _state.update { it.copy(searchQuery = query) }
-        loadItems(query)
-    }
-
-    private fun loadItems(query: String) {
-        viewModelScope.launch {
-            _state.update { it.copy(isLoading = true) }
-            getItems(query).fold(
-                onSuccess = { items -> _state.update { it.copy(items = items, isLoading = false) } },
-                onFailure = { e -> _state.update { it.copy(error = e.message, isLoading = false) } }
-            )
-        }
-    }
-}
-```
-
-### Recoger el estado en Compose
-
-```kotlin
-@Composable
-fun ItemListScreen(viewModel: ItemListViewModel = koinViewModel()) {
-    val state by viewModel.state.collectAsStateWithLifecycle()
-
-    ItemListContent(
-        state = state,
-        onSearch = viewModel::onSearch
-    )
-}
-
-@Composable
-private fun ItemListContent(
-    state: ItemListState,
-    onSearch: (String) -> Unit
-) {
-    // Composable sin estado — fácil de previsualizar y testear
-}
-```
-
-### Patrón event sink
-
-En pantallas complejas, usa una sealed interface para los eventos en lugar de múltiples lambdas de callback:
-
-```kotlin
-sealed interface ItemListEvent {
-    data class Search(val query: String) : ItemListEvent
-    data class Delete(val itemId: String) : ItemListEvent
-    data object Refresh : ItemListEvent
-}
-
-// En el ViewModel
-fun onEvent(event: ItemListEvent) {
-    when (event) {
-        is ItemListEvent.Search -> onSearch(event.query)
-        is ItemListEvent.Delete -> deleteItem(event.itemId)
-        is ItemListEvent.Refresh -> loadItems(_state.value.searchQuery)
-    }
-}
-
-// En el Composable — una sola lambda en vez de muchas
-ItemListContent(
-    state = state,
-    onEvent = viewModel::onEvent
-)
-```
-
-## Navegación
-
-### Navegación type-safe (Compose Navigation 2.8+)
-
-Define las rutas como objetos `@Serializable`:
-
-```kotlin
-@Serializable data object HomeRoute
-@Serializable data class DetailRoute(val id: String)
-@Serializable data object SettingsRoute
-
-@Composable
-fun AppNavHost(navController: NavHostController = rememberNavController()) {
-    NavHost(navController, startDestination = HomeRoute) {
-        composable<HomeRoute> {
-            HomeScreen(onNavigateToDetail = { id -> navController.navigate(DetailRoute(id)) })
-        }
-        composable<DetailRoute> { backStackEntry ->
-            val route = backStackEntry.toRoute<DetailRoute>()
-            DetailScreen(id = route.id)
-        }
-        composable<SettingsRoute> { SettingsScreen() }
-    }
-}
-```
-
-### Navegación con diálogos y bottom sheets
-
-Usa `dialog()` y patrones de overlay en lugar de mostrar/ocultar imperativo:
-
-```kotlin
-NavHost(navController, startDestination = HomeRoute) {
-    composable<HomeRoute> { /* ... */ }
-    dialog<ConfirmDeleteRoute> { backStackEntry ->
-        val route = backStackEntry.toRoute<ConfirmDeleteRoute>()
-        ConfirmDeleteDialog(
-            itemId = route.itemId,
-            onConfirm = { navController.popBackStack() },
-            onDismiss = { navController.popBackStack() }
-        )
-    }
-}
-```
-
-## Diseño de composables
-
-### APIs basadas en slots
-
-Diseña composables con parámetros slot para ganar flexibilidad:
-
-```kotlin
-@Composable
-fun AppCard(
-    modifier: Modifier = Modifier,
-    header: @Composable () -> Unit = {},
-    content: @Composable ColumnScope.() -> Unit,
-    actions: @Composable RowScope.() -> Unit = {}
-) {
-    Card(modifier = modifier) {
-        Column {
-            header()
-            Column(content = content)
-            Row(horizontalArrangement = Arrangement.End, content = actions)
-        }
-    }
-}
-```
-
-### Orden de los modifiers
-
-El orden de los modifiers importa — aplícalos en esta secuencia:
-
-```kotlin
-Text(
-    text = "Hola",
-    modifier = Modifier
-        .padding(16.dp)          // 1. Layout (padding, tamaño)
-        .clip(RoundedCornerShape(8.dp))  // 2. Forma
-        .background(Color.White) // 3. Dibujo (fondo, borde)
-        .clickable { }           // 4. Interacción
-)
-```
-
-## UI específica por plataforma en KMP
-
-### expect/actual para composables de plataforma
-
-```kotlin
-// commonMain
-@Composable
-expect fun PlatformStatusBar(darkIcons: Boolean)
-
-// androidMain
-@Composable
-actual fun PlatformStatusBar(darkIcons: Boolean) {
-    val systemUiController = rememberSystemUiController()
-    SideEffect { systemUiController.setStatusBarColor(Color.Transparent, darkIcons) }
-}
-
-// iosMain
-@Composable
-actual fun PlatformStatusBar(darkIcons: Boolean) {
-    // iOS lo maneja vía interoperabilidad con UIKit o Info.plist
-}
-```
-
-## Rendimiento
-
-### Tipos estables para recomposición omitible
-
-Marca las clases como `@Stable` o `@Immutable` cuando todas sus propiedades sean estables:
-
-```kotlin
-@Immutable
-data class ItemUiModel(
-    val id: String,
-    val title: String,
-    val description: String,
-    val progress: Float
-)
-```
-
-### Usa `key()` y las listas lazy correctamente
-
-```kotlin
-LazyColumn {
-    items(
-        items = items,
-        key = { it.id }  // Las claves estables habilitan reutilización de ítems y animaciones
-    ) { item ->
-        ItemRow(item = item)
-    }
-}
-```
-
-### Difiere las lecturas con `derivedStateOf`
-
-```kotlin
-val listState = rememberLazyListState()
-val showScrollToTop by remember {
-    derivedStateOf { listState.firstVisibleItemIndex > 5 }
-}
-```
-
-### Evita asignaciones dentro de la recomposición
-
-```kotlin
-// MAL — lambda y lista nuevas en cada recomposición
-items.filter { it.isActive }.forEach { ActiveItem(it, onClick = { handle(it) }) }
-
-// BIEN — usa key por ítem para que los callbacks queden atados a la fila correcta
-val activeItems = remember(items) { items.filter { it.isActive } }
-activeItems.forEach { item ->
-    key(item.id) {
-        ActiveItem(item, onClick = { handle(item) })
-    }
-}
-```
-
-## Theming
-
-### Theming dinámico con Material 3
-
-```kotlin
-@Composable
-fun AppTheme(
-    darkTheme: Boolean = isSystemInDarkTheme(),
-    dynamicColor: Boolean = true,
-    content: @Composable () -> Unit
-) {
-    val colorScheme = when {
-        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
-            if (darkTheme) dynamicDarkColorScheme(LocalContext.current)
-            else dynamicLightColorScheme(LocalContext.current)
-        }
-        darkTheme -> darkColorScheme()
-        else -> lightColorScheme()
-    }
-
-    MaterialTheme(colorScheme = colorScheme, content = content)
-}
-```
-
-## Antipatrones a evitar
-
-- Usar `mutableStateOf` en ViewModels cuando `MutableStateFlow` con `collectAsStateWithLifecycle` es más seguro respecto al ciclo de vida
-- Pasar el `NavController` hacia lo profundo de los composables — pasa lambdas de callback en su lugar
-- Computación pesada dentro de funciones `@Composable` — muévela al ViewModel o a `remember {}`
-- Usar `LaunchedEffect(Unit)` como sustituto del init del ViewModel — se re-ejecuta en cambios de configuración en algunos escenarios
-- Crear instancias nuevas de objetos en los parámetros de un composable — provoca recomposiciones innecesarias
-
-## Referencias
-
-Ver skill: `arquitectura-limpia-android` para estructura de módulos y capas.
-Ver skill: `corrutinas-flows-kotlin` para patrones de corrutinas y Flow.