@momo-kits/native-kits 0.0.1-beta.5 → 0.0.2-alpha.1-debug

package/CLAUDE.md

@@ -0,0 +1,99 @@
+# 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: AGP KMP `android` target (JVM 17, compile/min SDK 37/24; AGP 9.2.1, Gradle 9.5.0), `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
+
+Run `./gradlew :compose:testAndroidHostTest` for the request ownership tests in `commonTest`. Compile the relevant Android/iOS targets and use the sample app for visual checks.
+
+```bash
+./gradlew :compose:compileCommonMainKotlinMetadata        # validate commonMain (fast, do this first)
+./gradlew :compose:compileAndroidMain              # 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` (`application/`); `LocalNavigator`, `LocalMaxApi` (`navigation/`). Read with `X.current`.
+- **Design-system config** (`trustBanner`, `headerBar`, `headerGradient`): the host seeds `KitDesignSystemConfig.update(...)` once (same pattern as `KitFontScale`); `NavigationContainer` provides it as `LocalDesignSystemConfig` (param `designSystemConfig` → parent → global) and applies `headerBar` as the header image when the theme has none.
+- **Platform code** goes through `expect`/`actual` in `platform/` — never reference Android/iOS APIs from `commonMain` directly.
+- **Native bridge:** typed `IMaxApi` from NativeMaxApi `0.3.1` (`vn.momo.maxapi`, exposed as `LocalMaxApi`) is the host-app bridge. Toolkit uses `ToolkitOptions` to preserve custom groups and system-tool policy; pending callbacks are cancelled when their composition is disposed. Containers borrow the host client and must not close it.
+- Navigation uses a runtime `DynamicScreenRegistry`; overlays (modal/bottom-sheet/snackbar) go through `Navigator` + `OverplayComponentRegistry`.
+- **iOS swipe-back:** the host owns the only edge-pan recogniser and replays it through `HostBackGestureBridge` (`navigation/HostBackGestureBridge.kt`; the kit framework is never exported, so the host reaches it through its own Koin-provided facade): `checkCanPop` / `canPopInner` / `pop` route the back into the kit stack, `started` / `progressed` / `completed` / `cancelled` seek the NavHost transition, `shouldUseFloatingArrowBack` is set by bottom tabs. `NavigationContainer` attaches itself automatically (`AttachHostBackGesture`, iOS only, detached by identity on dispose) — hosts need no wrapper and no `setNavigator`. `maxApi` is a required parameter of `NavigationContainer` — every container, nested or root, is handed its host bridge explicitly.
+
+## 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`.
+
+### SwiftUI (`ios/Application/Localize.swift`)
+
+The SwiftUI port differs from Compose in one important way: **it follows the host app language by itself.**
+
+- `Localize.init` takes `languageSource: LanguageSource? = UserDefaultsLanguageSource()`. The default source KVO-observes `UserDefaults.standard["language"]` — the key the MoMo host writes from all three of its writers (the `RNResource` RN bridge, `JSONLocalization`, and the KMP `LocalizationProvider`) — so a language switch anywhere in the app republishes to every consumer. Pass `languageSource: nil` to opt out. The host key literal lives only in `UserDefaultsLanguageSource.defaultKey`.
+- Use `Localize.shared` unless a screen genuinely needs an isolated dictionary; it is also the `\.localize` environment default. Note `addTranslations` on it merges into a process-wide dictionary.
+- **Never set `\.localize` directly.** `EnvironmentValues.localize` stores a `LocalizeBox` snapshot, so consumers invalidate only when the injecting view re-runs its body. Always inject via `.momoLocalize(_:)` (`ios/Application/LocalizeModifier.swift`), which holds the object as `@ObservedObject` — that is what makes the snapshot refresh. `NavigationContainer` already does this; any bare `UIHostingController` root must do it too.
+- Read it with `@Environment(\.localize)`, not `@EnvironmentObject` — the environment default never traps, `@EnvironmentObject` fatal-errors when un-injected.
+- `Localize.normalize(_:)` is the single place that copes with the legacy JSON-quoted values (`"\"vi\""`) the host persists; anything that is not `en` resolves to `vi`.
+
+## Font scale (`scaleSize`)
+
+One formula, both platforms: the device-width scale (`width / 375`, capped at `+5pt`) and the OS Dynamic Type scale (capped at `1.5×`) are computed independently and the **larger wins**. When `useOSScaleRate` is false neither applies — the size is just multiplied by `userScaleRate`. Max font scale is fixed at 1.5; the old per-call/per-scope override is deprecated and ignored on both sides.
+
+- **Compose** — `const/Typography.kt` (`scaleSize` overloads for `Float`/`Dp`/`TextUnit`/`TextStyle`). The `TextUnit` overload divides by `density.fontScale` so Compose's own `sp` scaling isn't applied twice. Inputs: `LocalContext.current` (`MiniAppContext.userScaleRate` / `useOSScaleRate`, per-field) falling back to the `KitFontScale` global. On iOS, `platform/OsFontScale.ios.kt` observes `UIContentSizeCategoryDidChangeNotification` and overrides `LocalDensity` — Compose MP otherwise reads `fontScale` once at `ComposeUIViewController` creation. Wired at `NavigationContainer`.
+- **SwiftUI** — `ios/Typography/FontScale.swift`. `FontScale` is an immutable snapshot with `callAsFunction`, so a view reads `@Environment(\.momoFontScale) private var fontScale` and calls `fontScale(16)`. `FontScaleStore.shared` is the `ObservableObject` holding both inputs and the OS factor (it observes `UIContentSizeCategory.didChangeNotification`); the host pushes its preference with `update(userScaleRate:useOSScaleRate:)`.
+- **Never set `\.momoFontScale` directly** — same trap as `\.localize`. Inject via `.momoFontScale(_:context:)`, which holds the store as `@ObservedObject`; that is what re-publishes the snapshot. `NavigationContainer` does it (passing `MiniAppContext` so the per-mini-app override applies); a bare `UIHostingController` root must too. The environment default reads the live store, so an un-injected subtree still gets correct values — just not live ones.
+- The global `scaleSize(_:)` and `Font.appFont(size:)` remain for call sites that can't read the environment (UIKit bridges, free functions). They are **not** reactive. `Font.header_default_bold` & friends are computed `static var`s for the same reason — as stored `static let`s they froze the scale at first access. `UIViewRepresentable`s should read `context.environment.momoFontScale` instead, and re-apply the font in `updateUIView`, not only in `makeUIView`.
+
+## 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.