@momo-kits/native-kits 0.162.1-beta.1-debug → 0.162.1-beta.12-debug

package/CLAUDE.md

@@ -0,0 +1,78 @@
+# CLAUDE.md
+
+Guidance for working in this repo. Keep it accurate — update it when structure or commands change.
+
+## What this is
+
+`momo-native-kits` — MoMo's design-system / UI-kit as a **Kotlin Multiplatform + Compose Multiplatform** library, published for Android (AAR/Maven) and iOS (static framework + CocoaPods). It is the Compose port of the React Native `momo-kits`. Consumed by mini-apps embedded in the host MoMo app.
+
+- Artifact: `vn.momo.kits:kits` (version in `gradle.properties`). NPM mirror: `@momo-kits/native-kits`.
+- Targets: `androidTarget` (JVM 17, compile/min/target SDK 36/24/36), `iosArm64`, `iosSimulatorArm64` (framework `baseName = "kits"`, `isStatic = true`).
+- Kotlin 2.3.10, Compose MP 1.10.3.
+
+## Modules
+
+- `:compose` — the published library. All real code lives here.
+- `:sample:shared` + `:sample:androidApp` — demo app (`UIKitHome` lists all components). iOS demo in `sample/iosApp` (Xcode).
+
+## Source layout (`compose/src/commonMain/kotlin/vn/momo/kits/`)
+
+- `components/` — ~50 UI components, **one file per component** (`Button.kt`, `Input*.kt`, `PopupNotify.kt`, …).
+- `application/` — app-level context & config: `Context.kt` (CompositionLocals, `MiniAppContext`, `DesignSystemConfig`), `Localize.kt` (i18n: `LocalizationObject`, `Localize`, default dictionary), `Screen.kt`, header pieces. Also holds the **deprecated** `ApplicationContainer`.
+- `navigation/` — `NavigationContainer.kt` (**canonical entry point**), `Navigator.kt`, `Navigation.kt`, `StackScreen.kt`, `bottomtab/`, `component/`, `tracking/`.
+- `const/` — design tokens: `Theme.kt`, `Colors.kt`, `Typography.kt`, `Spacing.kt`, `Radius.kt`.
+- `layout/`, `modifier/`, `utils/`.
+- `platform/` — `Platform.kt` `expect` declarations, actualized in `androidMain` / `iosMain` (`Platform.android.kt`, `Platform.ios.kt`).
+
+## Build & verify
+
+No unit-test suite is configured. Validate changes by compiling the relevant target(s); use the sample app for visual checks.
+
+```bash
+./gradlew :compose:compileCommonMainKotlinMetadata        # validate commonMain (fast, do this first)
+./gradlew :compose:compileDebugKotlinAndroid              # Android target
+./gradlew :compose:linkDebugFrameworkIosSimulatorArm64    # iOS framework (slow)
+./gradlew :sample:androidApp:installDebug                 # run demo on device/emulator
+```
+
+Publishing is automated (`publish.sh` + GitLab CI on `[ci build]` / `main`). Do not publish manually unless asked: `sh publish.sh beta` / `sh publish.sh release` (Maven→GitLab + NPM).
+
+## Architecture essentials
+
+- **Entry point:** wrap content in `NavigationContainer(...)` from `navigation/`. It builds the `Navigator`, takes a host-supplied `Localize` (falls back to an empty one), and provides the CompositionLocals below. **Do not use** `ApplicationContainer` (`application/NavigationContainer.kt`) — deprecated and does **not** wire `LocalLocalize` / `LocalNavigator` / `LocalMaxApi`.
+- **Configuration flows via CompositionLocals**, not params. Public ones: `AppTheme`, `AppStatusBar`, `AppNavigationBar` (`const/Theme.kt`); `ApplicationContext`, `AppConfig`, `AppLanguage`, `LocalLocalize`, `ScaleSizeMaxRate` (`application/`); `LocalNavigator`, `LocalMaxApi` (`navigation/`). Read with `X.current`.
+- **Platform code** goes through `expect`/`actual` in `platform/` — never reference Android/iOS APIs from `commonMain` directly.
+- **Native bridge:** `IMaxApi` (`vn.momo.maxapi`, exposed as `LocalMaxApi`) is the host-app bridge (dismiss, tracking, device info, language).
+- Navigation uses a runtime `DynamicScreenRegistry`; overlays (modal/bottom-sheet/snackbar) go through `Navigator` + `OverplayComponentRegistry`.
+
+## i18n / Localize (port of RN `Localize`)
+
+- `application/Localize.kt`: everything i18n. `LocalizationObject` is a data class with required `vi` / `en` maps (`LocalizationObject(vi = mapOf(…), en = mapOf(…))`). `Localize` constructors take a `LocalizationObject` or a `(vi, en)` map pair; the constructor **merges** the kit defaults with the host data (host wins on key clash). Methods: `translate(key)` (missing/empty → returns the key), `translateData(map)` / `translateData(vi, en)`, `addTranslations` (existing keys win), `changeLanguage(lang)`. Default language `"vi"`, `"en"` only on exact match; language is snapshot state so a switch recomposes consumers.
+- The default dictionary lives **inside `Localize`** (companion `defaultLanguage`), **generated 1:1 from `momo-kits` RN `Assets/language.json`** — do not hand-edit that block; edit the RN source and regenerate.
+- The host creates one `Localize` and passes it in: `NavigationContainer(localize = myLocalize, …)`. There is **no** `language` param and `DesignSystemConfig` carries no translations — overrides go through the `Localize` constructor / `addTranslations`. Switch language at runtime with `myLocalize.changeLanguage("en")`.
+- Access in a `@Composable`: `LocalLocalize.current.translate("errorCode")`. Language is host-controlled, never read from the OS locale. `AppLanguage` is still provided (derived from `Localize.currentLanguage`) for older components that read it.
+- Some older components still do ad-hoc `AppLanguage.current` + `Map` lookups; new/changed code should use `LocalLocalize`.
+
+## Code conventions
+
+- **Tokens, not literals:** use `Colors`, `Typography`, `Spacing`, `Radius` objects and `AppTheme.current` for colors/styles. Per-component sizing is bundled in enums (e.g. `Button.Size(val value: ButtonSpecs)`).
+- **Composable signatures:** required params first, slot lambdas next, `modifier: Modifier = Modifier` **last**; give optional params sensible defaults.
+- **Stability:** annotate token/config data classes `@Stable`/`@Immutable`; memoize derived colors/styles/handlers with `remember(keys) { … }`.
+- **Custom modifiers** are preferred: `conditional(...)`, `setAutomationId(...)`, the `clickable` variants in `modifier/`.
+- Match the surrounding file's style when adding code.
+
+## Writing docs in code (follow this)
+
+Comments are **sparse and in English**. Document only what is **not obvious from the code** — non-obvious behavior, platform quirks, RN-parity semantics, memoization intent, or important gotchas worth flagging. Do **not**:
+
+- write KDoc walls or restate what the signature/code already says;
+- narrate obvious steps or add section-banner noise;
+- use a language other than English in code comments.
+
+Prefer one tight line at the surprising spot over a paragraph. Match the (low) comment density already in the codebase.
+
+## Gotchas
+
+- **Resource qualifier drift:** the generated Compose `Res` namespace is `vn.momo.uikits.resources`, but `utils/Resources.kt` and `platform/Platform.ios.kt` reference `vn.momo.compose.resources`. Keep bundled strings/dictionaries as plain Kotlin (the `defaultLanguage` map in `Localize.kt`), not `composeResources/values`, to avoid iOS framework resource-loading issues.
+- Prefer `NavigationContainer` over the deprecated `ApplicationContainer`; prefer `IMaxApi`/`LocalMaxApi` over the deprecated `PlatformApi`.
+- iOS strings/maps must survive Kotlin/Native framework packaging — keep them compiled-in, not loaded from resource bundles.

package/compose/build.gradle.kts

@@ -1,5 +1,5 @@
- import com.vanniktech.maven.publish.JavadocJar
- import com.vanniktech.maven.publish.KotlinMultiplatform
+// import com.vanniktech.maven.publish.JavadocJar
+// import com.vanniktech.maven.publish.KotlinMultiplatform
 import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 
 plugins {
@@ -7,7 +7,7 @@ plugins {
     alias(libs.plugins.android.library)
     alias(libs.plugins.compose)
     alias(libs.plugins.kotlin.compose.compiler)
-         alias(libs.plugins.vanniktech.mavenPublish)
+//         alias(libs.plugins.vanniktech.mavenPublish)
     id(libs.plugins.jetbrains.kotlin.cocoapods.get().pluginId)
     kotlin("plugin.serialization")
 }
@@ -40,7 +40,7 @@ kotlin {
     }
 
     cocoapods {
-        version = "0.161.0-debug"
+        version = "0.162.1-beta.12-debug"
         summary = "IOS Shared module"
         homepage = "https://momo.vn"
         ios.deploymentTarget = "15.0"
@@ -59,7 +59,7 @@ kotlin {
 
     sourceSets {
         all {
-            languageSettings.optIn("vn.momo.kits.utils.Deprecated.InternalApi")
+            languageSettings.optIn("vn.momo.kits.modifier.InternalApi")
         }
         commonMain.dependencies {
             implementation(compose.runtime)
@@ -77,6 +77,7 @@ kotlin {
             implementation(libs.kotlinx.datetime)
             api(libs.native.max.api)
             implementation(libs.compottie)
+            implementation(libs.gif.image)
         }
         androidMain.dependencies {
             implementation(libs.ktor.client.okhttp)
@@ -90,7 +91,7 @@ kotlin {
 
 android {
     namespace = "vn.momo.kits.kits"
-    compileSdk = 36
+    compileSdk = 35
     compileOptions {
         sourceCompatibility = JavaVersion.VERSION_17
         targetCompatibility = JavaVersion.VERSION_17
@@ -135,55 +136,55 @@ compose {
     }
 }
 
- publishing {
-     repositories {
-         maven {
-             name = "${gitlabRepo}Packages"
-             credentials {
-                 username = gitlabUser
-                 password = gitlabKey
-             }
-             url = uri(gitlabUrl)
-         }
-     }
- }
-
- mavenPublishing {
-     configure(
-         KotlinMultiplatform(
-             javadocJar = JavadocJar.Empty(),
-             sourcesJar = true,
-             androidVariantsToPublish = listOf("release")
-         )
-     )
-
-     repositories {
-         maven {
-             name = "${gitlabRepo}Packages"
-             credentials { username = gitlabUser; password = gitlabKey }
-             url = uri(gitlabUrl)
-         }
-     }
-
-     coordinates(gitlabGroup, gitlabArtifactId, gitlabVersion)
-
-     pom {
-         name = "$gitlabName Klib"
-         description = gitlabName
-         url = "https://gitlab.mservice.com.vn"
-         licenses {
-             license {
-                 name = "The Apache License, Version 2.0"
-                 url = "https://www.apache.org/licenses/LICENSE-2.0.txt"
-                 distribution = "https://www.apache.org/licenses/LICENSE-2.0.txt"
-             }
-         }
-         developers {
-             developer {
-                 id = "kotlin-hands-on"
-                 name = "Kotlin Developer Advocate"
-                 url = "https://github.com/kotlin-hands-on/"
-             }
-         }
-     }
- }
+// publishing {
+//     repositories {
+//         maven {
+//             name = "${gitlabRepo}Packages"
+//             credentials {
+//                 username = gitlabUser
+//                 password = gitlabKey
+//             }
+//             url = uri("$gitlabUrl")
+//         }
+//     }
+// }
+
+// mavenPublishing {
+//     configure(
+//         KotlinMultiplatform(
+//             javadocJar = JavadocJar.Empty(),
+//             sourcesJar = true,
+//             androidVariantsToPublish = listOf("release")
+//         )
+//     )
+// 
+//     repositories {
+//         maven {
+//             name = "${gitlabRepo}Packages"
+//             credentials { username = gitlabUser; password = gitlabKey }
+//             url = uri("$gitlabUrl")
+//         }
+//     }
+// 
+//     coordinates(gitlabGroup.toString(), gitlabArtifactId, gitlabVersion.toString())
+// 
+//     pom {
+//         name = "$gitlabName Klib"
+//         description = "$gitlabName"
+//         url = "https://gitlab.mservice.com.vn"
+//         licenses {
+//             license {
+//                 name = "The Apache License, Version 2.0"
+//                 url = "https://www.apache.org/licenses/LICENSE-2.0.txt"
+//                 distribution = "https://www.apache.org/licenses/LICENSE-2.0.txt"
+//             }
+//         }
+//         developers {
+//             developer {
+//                 id = "kotlin-hands-on"
+//                 name = "Kotlin Developer Advocate"
+//                 url = "https://github.com/kotlin-hands-on/"
+//             }
+//         }
+//     }
+// }

package/compose/build.gradle.kts.backup

@@ -1,5 +1,5 @@
- import com.vanniktech.maven.publish.JavadocJar
- import com.vanniktech.maven.publish.KotlinMultiplatform
+import com.vanniktech.maven.publish.JavadocJar
+import com.vanniktech.maven.publish.KotlinMultiplatform
 import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 
 plugins {
@@ -7,7 +7,7 @@ plugins {
     alias(libs.plugins.android.library)
     alias(libs.plugins.compose)
     alias(libs.plugins.kotlin.compose.compiler)
-         alias(libs.plugins.vanniktech.mavenPublish)
+    alias(libs.plugins.vanniktech.mavenPublish)
     id(libs.plugins.jetbrains.kotlin.cocoapods.get().pluginId)
     kotlin("plugin.serialization")
 }
@@ -40,7 +40,7 @@ kotlin {
     }
 
     cocoapods {
-        version = "0.161.0-debug"
+        version = gitlabVersion
         summary = "IOS Shared module"
         homepage = "https://momo.vn"
         ios.deploymentTarget = "15.0"
@@ -59,7 +59,7 @@ kotlin {
 
     sourceSets {
         all {
-            languageSettings.optIn("vn.momo.kits.utils.Deprecated.InternalApi")
+            languageSettings.optIn("vn.momo.kits.modifier.InternalApi")
         }
         commonMain.dependencies {
             implementation(compose.runtime)
@@ -77,6 +77,7 @@ kotlin {
             implementation(libs.kotlinx.datetime)
             api(libs.native.max.api)
             implementation(libs.compottie)
+            implementation(libs.gif.image)
         }
         androidMain.dependencies {
             implementation(libs.ktor.client.okhttp)
@@ -89,14 +90,14 @@ kotlin {
 }
 
 android {
-    namespace = "vn.momo.kits.kits"
-    compileSdk = 36
+    namespace = "$gitlabGroup.$gitlabArtifactId"
+    compileSdk = libs.versions.android.compileSdk.get().toInt()
     compileOptions {
         sourceCompatibility = JavaVersion.VERSION_17
         targetCompatibility = JavaVersion.VERSION_17
     }
     defaultConfig {
-        minSdk = 24
+        minSdk = libs.versions.android.minSdk.get().toInt()
     }
 }
 
@@ -135,55 +136,55 @@ compose {
     }
 }
 
- publishing {
-     repositories {
-         maven {
-             name = "${gitlabRepo}Packages"
-             credentials {
-                 username = gitlabUser
-                 password = gitlabKey
-             }
-             url = uri(gitlabUrl)
-         }
-     }
- }
-
- mavenPublishing {
-     configure(
-         KotlinMultiplatform(
-             javadocJar = JavadocJar.Empty(),
-             sourcesJar = true,
-             androidVariantsToPublish = listOf("release")
-         )
-     )
-
-     repositories {
-         maven {
-             name = "${gitlabRepo}Packages"
-             credentials { username = gitlabUser; password = gitlabKey }
-             url = uri(gitlabUrl)
-         }
-     }
-
-     coordinates(gitlabGroup, gitlabArtifactId, gitlabVersion)
-
-     pom {
-         name = "$gitlabName Klib"
-         description = gitlabName
-         url = "https://gitlab.mservice.com.vn"
-         licenses {
-             license {
-                 name = "The Apache License, Version 2.0"
-                 url = "https://www.apache.org/licenses/LICENSE-2.0.txt"
-                 distribution = "https://www.apache.org/licenses/LICENSE-2.0.txt"
-             }
-         }
-         developers {
-             developer {
-                 id = "kotlin-hands-on"
-                 name = "Kotlin Developer Advocate"
-                 url = "https://github.com/kotlin-hands-on/"
-             }
-         }
-     }
- }
+publishing {
+    repositories {
+        maven {
+            name = "${gitlabRepo}Packages"
+            credentials {
+                username = gitlabUser
+                password = gitlabKey
+            }
+            url = uri("$gitlabUrl")
+        }
+    }
+}
+
+mavenPublishing {
+    configure(
+        KotlinMultiplatform(
+            javadocJar = JavadocJar.Empty(),
+            sourcesJar = true,
+            androidVariantsToPublish = listOf("release")
+        )
+    )
+
+    repositories {
+        maven {
+            name = "${gitlabRepo}Packages"
+            credentials { username = gitlabUser; password = gitlabKey }
+            url = uri("$gitlabUrl")
+        }
+    }
+
+    coordinates(gitlabGroup.toString(), gitlabArtifactId, gitlabVersion.toString())
+
+    pom {
+        name = "$gitlabName Klib"
+        description = "$gitlabName"
+        url = "https://gitlab.mservice.com.vn"
+        licenses {
+            license {
+                name = "The Apache License, Version 2.0"
+                url = "https://www.apache.org/licenses/LICENSE-2.0.txt"
+                distribution = "https://www.apache.org/licenses/LICENSE-2.0.txt"
+            }
+        }
+        developers {
+            developer {
+                id = "kotlin-hands-on"
+                name = "Kotlin Developer Advocate"
+                url = "https://github.com/kotlin-hands-on/"
+            }
+        }
+    }
+}

package/compose/compose.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |spec|
     spec.name                     = 'compose'
-    spec.version                  = '0.161.0-debug'
+    spec.version                  = '0.163.1-beta.1'
     spec.homepage                 = 'https://momo.vn'
     spec.source                   = { :http=> ''}
     spec.authors                  = ''

package/compose/src/commonMain/kotlin/vn/momo/kits/application/Context.kt

@@ -10,7 +10,7 @@ data class FeatureFlags(
 )
 
 @Immutable
-data class KitConfig(
+data class DesignSystemConfig(
     val trustBanner: TrustBannerData? = null,
     val headerBar: String? = null,
     val headerGradient: String? = null,
@@ -28,7 +28,7 @@ data class MiniAppContext(
     val providerId: String = "",
     val permissions: List<Map<String, Any>>? = emptyList(),
     val features: FeatureFlags? = null,
-    val scaleSizeMaxRate: Float? = null,
+    val fontScaleConfig: FontScaleConfig? = null,
 ) {
     companion object {
 
@@ -60,7 +60,7 @@ data class MiniAppContext(
                 providerId = parent.providerId.ifBlank { child.providerId },
                 permissions = if (!parent.permissions.isNullOrEmpty()) parent.permissions else child.permissions,
                 features = mergeFeatureFlags(parent.features, child.features),
-                scaleSizeMaxRate = parent.scaleSizeMaxRate ?: child.scaleSizeMaxRate,
+                fontScaleConfig = parent.fontScaleConfig ?: child.fontScaleConfig,
             )
         }
 
@@ -88,17 +88,9 @@ data class ComponentInformation(
     val action: String? = null
 )
 
-var IsShowBaseLineDebug = true
+var IsShowBaseLineDebug = false
 
-val ApplicationContext = staticCompositionLocalOf<MiniAppContext?> {
-    null
-}
-
-val AppConfig = staticCompositionLocalOf<KitConfig?> {
-    null
-}
-
-val AppLanguage = staticCompositionLocalOf<String?> {
+val LocalContext = staticCompositionLocalOf<MiniAppContext?> {
     null
 }
 
@@ -106,4 +98,11 @@ val LocalComponentInformation = staticCompositionLocalOf<ComponentInformation?>
     null
 }
 
-val ScaleSizeMaxRate = staticCompositionLocalOf<Float?> { null }
+@Immutable
+data class FontScaleConfig(
+    val useOSFontScale: Boolean = true,
+    val userScaleRate: Float? = null,
+    val osFontScale: Float? = null,
+)
+
+val LocalFontScaleConfig = staticCompositionLocalOf { FontScaleConfig() }

package/compose/src/commonMain/kotlin/vn/momo/kits/application/HeaderRight.kt

@@ -117,7 +117,7 @@ private fun ToolkitHeaderRight(
     var isFavorite by remember { mutableStateOf(false) }
     val isLoading by remember { mutableStateOf(false) }
     val api = PlatformApi.current as? ComposeApi
-    val context = ApplicationContext.current
+    val context = LocalContext.current
 
     fun onPressShortcut() {
         api?.request("onToolAction", mapOf("item" to mapOf("key" to "onFavorite"))) {
@@ -262,7 +262,7 @@ fun NavigationButton(
         modifier = Modifier
             .size(28.dp)
             .clickable(enabled = !disabled, onClick = onClick)
-            
+
     ) {
         Box(
             modifier = Modifier