@momo-kits/native-kits 0.157.1-skill.1-debug → 0.157.1-skill.3-debug

package/.claude/momo-native-kits-skill/references/navigation.md

@@ -0,0 +1,475 @@
+# Navigation System
+
+## Key Points (IMPORTANT)
+
+- **ONE NavigationContainer per Fragment** - All screens in one container
+- **setOptions in LaunchedEffect(Unit)** - NOT in composable root
+- **LocalNavigation.current** - For setOptions (header, scroll, footer)
+- **LocalNavigator.current** - For push/pop/present/showModal/showBottomSheet
+
+## Overview
+
+MoMo Native Kits provides a comprehensive navigation system built on top of Jetpack Navigation Compose.
+
+**Package:** `vn.momo.kits.navigation`
+
+## Architecture
+
+### Single NavigationContainer Rule
+
+**IMPORTANT:** There should only be **ONE** `NavigationContainer` per Fragment/Activity. All screens are managed within this single container.
+
+```kotlin
+// ✅ CORRECT - Single NavigationContainer
+@Composable
+fun MyApp() {
+    NavigationContainer(
+        initialScreen = {
+            HomeScreen()
+        },
+        options = NavigationOptions(
+            headerTitle = HeaderTitle.Default("My App")
+        )
+    ) {
+        // All screens pushed here
+    }
+}
+```
+
+### Navigation Context
+
+Within any screen, access navigation through:
+
+```kotlin
+val navigator = LocalNavigator.current  // For screen navigation (push, pop, etc.)
+val navigation = LocalNavigation.current  // For setting screen options
+```
+
+---
+
+## NavigationContainer
+
+**File:** `vn/momo/kits/navigation/NavigationContainer.kt`
+
+### Parameters
+
+```kotlin
+@Composable
+fun NavigationContainer(
+    initialScreen: @Composable () -> Unit,  // First screen to show
+    options: NavigationOptions = NavigationOptions(),  // Global options
+    modifier: Modifier = Modifier,
+    applicationContext: MiniAppContext? = null
+)
+```
+
+### NavigationOptions
+
+```kotlin
+data class NavigationOptions(
+    val headerTitle: HeaderTitle? = null,
+    val headerType: HeaderType = HeaderType.DEFAULT,
+    val headerRight: @Composable () -> Unit = {},
+    val hiddenBack: Boolean = false,
+    val footerComponent: @Composable () -> Unit = {},
+    val floatingButtonProps: FloatingButtonProps? = null,
+    val scrollData: ScrollData? = null,
+    val keyboardOptions: KeyboardOptions? = null,
+    val statusBarStyle: StatusBarStyle = StatusBarStyle.LIGHT_CONTENT,
+    val statusBarColor: Color? = null
+)
+```
+
+### Full Example
+
+```kotlin
+import vn.momo.kits.navigation.NavigationContainer
+import vn.momo.kits.navigation.NavigationOptions
+import vn.momo.kits.navigation.component.HeaderRight
+import vn.momo.kits.navigation.component.HeaderTitle
+import vn.momo.kits.navigation.component.HeaderType
+
+@Composable
+fun MyApp() {
+    val inputSearch = remember { mutableStateOf("") }
+
+    Box(Modifier.fillMaxSize()) {
+        NavigationContainer(
+            initialScreen = {
+                HomeScreen()
+            },
+            options = NavigationOptions(
+                headerTitle = HeaderTitle.Default("MoMo App"),
+                headerType = HeaderType.Extended(
+                    useAnimated = true,
+                    inputSearchProps = InputSearchProps(
+                        text = inputSearch,
+                        placeholder = "Search...",
+                        onChangeText = { inputSearch.value = it }
+                    )
+                ),
+                headerRight = {
+                    HeaderRight.Toolkit(useShortcut = true)
+                },
+                hiddenBack = false,
+                footerComponent = {
+                    Button(title = "Footer Button", onClick = {})
+                },
+                floatingButtonProps = FloatingButtonProps(
+                    icon = "ic_warning",
+                    iconColor = Color.White,
+                    label = "Help",
+                    onClick = { /* Handle click */ },
+                    size = FABSize.DEFAULT,
+                    position = FABPosition.END
+                )
+            )
+        )
+    }
+}
+```
+
+---
+
+## setOptions - Dynamic Screen Configuration
+
+`setOptions` is used to dynamically change screen options **after** the screen has been pushed. This is called inside `LaunchedEffect(Unit)`.
+
+### When to Use setOptions
+
+1. **On screen initialization** - Set header type, scroll behavior
+2. **In response to user actions** - Change header title, show/hide components
+3. **To configure scroll behavior** - Connect scroll state to header animation
+
+### Basic Usage
+
+```kotlin
+@Composable
+fun MyScreen() {
+    val navigation = LocalNavigation.current
+
+    LaunchedEffect(Unit) {
+        navigation.setOptions(
+            headerTitle = HeaderTitle.Default("My Screen"),
+            headerType = HeaderType.DEFAULT
+        )
+    }
+
+    // Screen content
+}
+```
+
+### Change Header Title Dynamically
+
+```kotlin
+@Composable
+fun DynamicTitleScreen() {
+    val navigation = LocalNavigation.current
+    val title = remember { mutableStateOf("") }
+
+    Column(modifier = Modifier.padding(16.dp)) {
+        Input(
+            text = title,
+            onChangeText = { title.value = it },
+            floatingValue = "Enter title"
+        )
+
+        Button(
+            title = "Change Title",
+            onClick = {
+                navigation.setOptions(
+                    headerTitle = HeaderTitle.Default(title.value)
+                )
+            }
+        )
+    }
+}
+```
+
+### Configure Scroll Behavior
+
+```kotlin
+@Composable
+fun ScrollableScreen() {
+    val navigation = LocalNavigation.current
+    val scrollState = rememberScrollState()
+
+    LaunchedEffect(Unit) {
+        navigation.setOptions(
+            scrollData = ScrollData(
+                scrollState = scrollState
+            )
+        )
+    }
+
+    LazyColumn(state = scrollState) {
+        // Content
+    }
+}
+```
+
+### Footer Component
+
+```kotlin
+@Composable
+fun ScreenWithFooter() {
+    val navigation = LocalNavigation.current
+
+    LaunchedEffect(Unit) {
+        navigation.setOptions(
+            footerComponent = {
+                Button(
+                    title = "Submit",
+                    onClick = { /* Submit */ }
+                )
+            }
+        )
+    }
+
+    // Screen content
+}
+```
+
+### Prevent Back with Confirmation
+
+```kotlin
+@Composable
+fun PreventBackScreen() {
+    val navigation = LocalNavigation.current
+    val navigator = LocalNavigator.current
+
+    LaunchedEffect(Unit) {
+        navigation.setOptions(
+            headerBackProps = HeaderBackProps(
+                preventBack = PopupNotifyProps(
+                    onIconClose = { navigator.pop() },
+                    primary = PopupAction(
+                        title = "Go back",
+                        onPress = { navigator.pop() }
+                    ),
+                    secondary = PopupAction(
+                        title = "Stay",
+                        onPress = { /* Do nothing */ }
+                    )
+                )
+            )
+        )
+    }
+}
+```
+
+---
+
+## Navigator - Screen Navigation
+
+Use `LocalNavigator.current` for navigation actions.
+
+### Navigation Actions
+
+```kotlin
+val navigator = LocalNavigator.current
+
+// Push a new screen
+navigator.push({ ScreenContent() })
+
+// Push with options
+navigator.push(
+    content = { ScreenContent() },
+    options = NavigationOptions(
+        headerTitle = HeaderTitle.Default("New Screen")
+    )
+)
+
+// Pop current screen
+navigator.pop()
+
+// Pop with callback
+navigator.pop(callBack = { /* Called after pop */ })
+
+// Present (modal)
+navigator.present({ ModalContent() })
+
+// Replace current screen
+navigator.replace({ NewScreen() })
+
+// Reset to new screen (clear stack)
+navigator.reset({ NewStartScreen() })
+
+// Show modal overlay
+navigator.showModal(
+    content = { /* Modal content */ },
+    barrierDismissible = true,
+    onDismiss = { /* Handle dismiss */ }
+)
+
+// Show bottom sheet
+navigator.showBottomSheet(
+    content = { /* Sheet content */ },
+    barrierDismissible = true,
+    onDismiss = { /* Handle dismiss */ }
+)
+```
+
+---
+
+## Header Types
+
+### HeaderType.None
+```kotlin
+headerType = HeaderType.None  // No header
+```
+
+### HeaderType.Default
+```kotlin
+headerType = HeaderType.Default
+```
+
+### HeaderType.Extended
+```kotlin
+headerType = HeaderType.Extended(
+    useAnimated = true,
+    inputSearchProps = InputSearchProps(
+        text = searchState,
+        placeholder = "Search...",
+        onChangeText = { /* Handle */ }
+    )
+)
+```
+
+### HeaderType.Animated
+```kotlin
+headerType = HeaderType.Animated(
+    isSurface = true,
+    aspectRatio = AnimatedHeaderRatio.RATIO_16_9,
+    composable = {
+        Image(
+            source = "https://example.com/header.jpg",
+            modifier = Modifier.fillMaxSize()
+        )
+    }
+)
+```
+
+---
+
+## Bottom Tab Navigation
+
+**File:** `vn.momo/kits/navigation/bottomtab/BottomTab.kt`
+
+### Parameters
+
+```kotlin
+@Composable
+fun BottomTab(
+    items: List<BottomTabItem>,  // List of tabs
+    floatingButton: BottomTabFloatingButton? = null  // Optional FAB
+)
+```
+
+### BottomTabItem
+
+```kotlin
+data class BottomTabItem(
+    val name: String,                      // Tab identifier
+    val label: String,                     // Tab label
+    val icon: String,                      // Icon name
+    val showDot: Boolean = false,          // Show notification dot
+    val badgeLabel: String? = null,         // Badge text
+    val screen: @Composable () -> Unit,     // Screen content
+    val options: NavigationOptions? = null, // Tab-specific options
+    val initialParams: Any? = null          // Initial params
+)
+```
+
+### BottomTabFloatingButton
+
+```kotlin
+data class BottomTabFloatingButton(
+    val icon: String,           // FAB icon
+    val label: String,         // FAB label
+    val onPress: () -> Unit    // Click handler
+)
+```
+
+### Example
+
+```kotlin
+@Composable
+fun MainScreen() {
+    val navigator = LocalNavigator.current
+
+    BottomTab(
+        items = listOf(
+            BottomTabItem(
+                name = "home",
+                label = "Trang chủ",
+                icon = "ic_home",
+                screen = { HomeScreen() },
+                options = NavigationOptions(
+                    headerTitle = HeaderTitle.Default("Trang chủ")
+                )
+            ),
+            BottomTabItem(
+                name = "wallet",
+                label = "Ví của tôi",
+                icon = "ic_wallet",
+                screen = { WalletScreen() },
+                options = NavigationOptions(
+                    headerTitle = HeaderTitle.Default("Ví của tôi")
+                ),
+                badgeLabel = "3"
+            ),
+            BottomTabItem(
+                name = "history",
+                label = "Lịch sử",
+                icon = "ic_history",
+                screen = { HistoryScreen() }
+            ),
+            BottomTabItem(
+                name = "profile",
+                label = "Tài khoản",
+                icon = "ic_profile",
+                screen = { ProfileScreen() }
+            )
+        ),
+        floatingButton = BottomTabFloatingButton(
+            icon = "ic_qr",
+            label = "Quét QR",
+            onPress = { navigator.push({ QRScannerScreen() }) }
+        )
+    )
+}
+```
+
+### Changing Tab Header Dynamically
+
+```kotlin
+BottomTabItem(
+    name = "tab2",
+    label = "Tab 2",
+    icon = "ic_tab",
+    screen = {
+        Box(Modifier.fillMaxSize().background(Color.Red)) {
+            val navigation = LocalNavigation.current
+            Button(onClick = {
+                navigation.setOptions(
+                    headerTitle = HeaderTitle.Default("Changed Title")
+                )
+            }, title = "Change Title")
+        }
+    },
+    options = NavigationOptions(headerTitle = HeaderTitle.Default("Tab 2"))
+)
+```
+
+---
+
+## Best Practices
+
+1. **One NavigationContainer per Fragment** - Don't nest containers
+2. **Use setOptions in LaunchedEffect** - Set options when screen loads
+3. **Use NavigationOptions in push()** - Set options when pushing screens
+4. **Connect scroll state early** - Set scrollData in LaunchedEffect
+5. **Use meaningful screen names** - For debugging and analytics
+6. **Handle back press properly** - Use preventBack for confirmation dialogs
+7. **BottomTab wraps entire app** - It's the root navigation

package/.claude/momo-native-kits-skill/references/popup.md

@@ -0,0 +1,97 @@
+# PopupNotify
+
+**File:** `vn.momo/kits/components/PopupNotify.kt`
+
+## Parameters
+
+```kotlin
+@Composable
+fun PopupNotify(
+    props: PopupNotifyProps
+)
+
+data class PopupNotifyProps(
+    val title: String,
+    val message: String? = null,
+    val type: PopupNotifyType = PopupNotifyType.INFO,
+    val primary: PopupAction? = null,
+    val secondary: PopupAction? = null,
+    val onIconClose: (() -> Unit)? = null,
+    val isVisible: Boolean = true
+)
+
+data class PopupAction(
+    val title: String,
+    val onPress: () -> Unit
+)
+
+enum class PopupNotifyType {
+    SUCCESS, ERROR, WARNING, INFO
+}
+```
+
+## Basic
+
+```kotlin
+PopupNotify(
+    props = PopupNotifyProps(
+        title = "Thành công",
+        message = "Giao dịch đã được xử lý",
+        type = PopupNotifyType.SUCCESS,
+        onIconClose = { showPopup = false }
+    )
+)
+```
+
+## With Actions
+
+```kotlin
+PopupNotify(
+    props = PopupNotifyProps(
+        title = "Xác nhận",
+        message = "Bạn có chắc muốn xóa?",
+        type = PopupNotifyType.WARNING,
+        primary = PopupAction(title = "Xóa", onPress = { /* delete */ }),
+        secondary = PopupAction(title = "Hủy", onPress = { /* cancel */ }),
+        onIconClose = { showPopup = false }
+    )
+)
+```
+
+---
+
+# PopupPromotion
+
+**File:** `vn/momo/kits/components/PopupPromotion.kt`
+
+## Parameters
+
+```kotlin
+@Composable
+fun PopupPromotion(
+    isVisible: Boolean,
+    imageUrl: String,
+    title: String = "",
+    description: String = "",
+    primaryButtonText: String = "",
+    secondaryButtonText: String = "",
+    onPrimaryClick: () -> Unit = {},
+    onSecondaryClick: () -> Unit = {},
+    onDismiss: () -> Unit
+)
+```
+
+## Usage
+
+```kotlin
+PopupPromotion(
+    isVisible = showPromotion,
+    imageUrl = "https://example.com/promotion.jpg",
+    title = "Giảm 50%",
+    description = "Ưu đãi đặc biệt",
+    primaryButtonText = "Nhận ngay",
+    secondaryButtonText = "Để sau",
+    onPrimaryClick = { /* claim */ },
+    onDismiss = { showPromotion = false }
+)
+```

package/.claude/momo-native-kits-skill/references/radio.md

@@ -0,0 +1,60 @@
+# Radio
+
+**File:** `vn.momo/kits/components/Radio.kt`
+
+## Parameters
+
+```kotlin
+@Composable
+fun Radio(
+    value: T,                          // Required: This radio's value
+    onChange: (T) -> Unit,            // Required: Selection callback
+    groupValue: T,                    // Required: Currently selected value
+    modifier: Modifier = Modifier,
+    label: String = "",                // Label text
+    enabled: Boolean = true
+)
+```
+
+## Usage
+
+```kotlin
+var selectedOption by remember { mutableStateOf("option1") }
+
+Column {
+    Radio(
+        value = "option1",
+        onChange = { selectedOption = it },
+        groupValue = selectedOption,
+        label = "Option 1"
+    )
+
+    Radio(
+        value = "option2",
+        onChange = { selectedOption = it },
+        groupValue = selectedOption,
+        label = "Option 2"
+    )
+}
+```
+
+## With Enum
+
+```kotlin
+enum class Gender { MALE, FEMALE, OTHER }
+
+var gender by remember { mutableStateOf(Gender.MALE) }
+
+Gender.entries.forEach { g ->
+    Radio(
+        value = g,
+        onChange = { gender = it },
+        groupValue = gender,
+        label = when (g) {
+            Gender.MALE -> "Nam"
+            Gender.FEMALE -> "Nữ"
+            Gender.OTHER -> "Khác"
+        }
+    )
+}
+```

package/.claude/momo-native-kits-skill/references/skeleton.md

@@ -0,0 +1,40 @@
+# Skeleton
+
+**File:** `vn.momo/kits/components/Skeleton.kt`
+
+## Parameters
+
+```kotlin
+@Composable
+fun Skeleton(
+    modifier: Modifier = Modifier,
+    width: Dp? = null,           // Specific width or null for wrap
+    height: Dp = 20.dp,          // Height
+    cornerRadius: Dp = Radius.S,  // Corner radius
+    animate: Boolean = true        // Enable animation
+)
+```
+
+## Usage
+
+```kotlin
+@Composable
+fun LoadingCard() {
+    Card(modifier = Modifier.fillMaxWidth()) {
+        Column(modifier = Modifier.padding(16.dp)) {
+            Row {
+                Skeleton(width = 60.dp, height = 60.dp, cornerRadius = 8.dp)
+                Column(modifier = Modifier.padding(start = 12.dp)) {
+                    Skeleton(width = 120.dp)
+                    Spacer(modifier = Modifier.height(8.dp))
+                    Skeleton(width = 80.dp)
+                }
+            }
+            Spacer(modifier = Modifier.height(12.dp))
+            Skeleton()
+            Spacer(modifier = Modifier.height(4.dp))
+            Skeleton(width = 200.dp)
+        }
+    }
+}
+```