@momo-kits/native-kits 0.162.6 → 0.162.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CLAUDE.md +78 -0
- package/package.json +1 -1
package/CLAUDE.md
ADDED
|
@@ -0,0 +1,78 @@
|
|
|
1
|
+
# CLAUDE.md
|
|
2
|
+
|
|
3
|
+
Guidance for working in this repo. Keep it accurate — update it when structure or commands change.
|
|
4
|
+
|
|
5
|
+
## What this is
|
|
6
|
+
|
|
7
|
+
`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.
|
|
8
|
+
|
|
9
|
+
- Artifact: `vn.momo.kits:kits` (version in `gradle.properties`). NPM mirror: `@momo-kits/native-kits`.
|
|
10
|
+
- Targets: `androidTarget` (JVM 17, compile/min/target SDK 36/24/36), `iosArm64`, `iosSimulatorArm64` (framework `baseName = "kits"`, `isStatic = true`).
|
|
11
|
+
- Kotlin 2.3.10, Compose MP 1.10.3.
|
|
12
|
+
|
|
13
|
+
## Modules
|
|
14
|
+
|
|
15
|
+
- `:compose` — the published library. All real code lives here.
|
|
16
|
+
- `:sample:shared` + `:sample:androidApp` — demo app (`UIKitHome` lists all components). iOS demo in `sample/iosApp` (Xcode).
|
|
17
|
+
|
|
18
|
+
## Source layout (`compose/src/commonMain/kotlin/vn/momo/kits/`)
|
|
19
|
+
|
|
20
|
+
- `components/` — ~50 UI components, **one file per component** (`Button.kt`, `Input*.kt`, `PopupNotify.kt`, …).
|
|
21
|
+
- `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`.
|
|
22
|
+
- `navigation/` — `NavigationContainer.kt` (**canonical entry point**), `Navigator.kt`, `Navigation.kt`, `StackScreen.kt`, `bottomtab/`, `component/`, `tracking/`.
|
|
23
|
+
- `const/` — design tokens: `Theme.kt`, `Colors.kt`, `Typography.kt`, `Spacing.kt`, `Radius.kt`.
|
|
24
|
+
- `layout/`, `modifier/`, `utils/`.
|
|
25
|
+
- `platform/` — `Platform.kt` `expect` declarations, actualized in `androidMain` / `iosMain` (`Platform.android.kt`, `Platform.ios.kt`).
|
|
26
|
+
|
|
27
|
+
## Build & verify
|
|
28
|
+
|
|
29
|
+
No unit-test suite is configured. Validate changes by compiling the relevant target(s); use the sample app for visual checks.
|
|
30
|
+
|
|
31
|
+
```bash
|
|
32
|
+
./gradlew :compose:compileCommonMainKotlinMetadata # validate commonMain (fast, do this first)
|
|
33
|
+
./gradlew :compose:compileDebugKotlinAndroid # Android target
|
|
34
|
+
./gradlew :compose:linkDebugFrameworkIosSimulatorArm64 # iOS framework (slow)
|
|
35
|
+
./gradlew :sample:androidApp:installDebug # run demo on device/emulator
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
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).
|
|
39
|
+
|
|
40
|
+
## Architecture essentials
|
|
41
|
+
|
|
42
|
+
- **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`.
|
|
43
|
+
- **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`.
|
|
44
|
+
- **Platform code** goes through `expect`/`actual` in `platform/` — never reference Android/iOS APIs from `commonMain` directly.
|
|
45
|
+
- **Native bridge:** `IMaxApi` (`vn.momo.maxapi`, exposed as `LocalMaxApi`) is the host-app bridge (dismiss, tracking, device info, language).
|
|
46
|
+
- Navigation uses a runtime `DynamicScreenRegistry`; overlays (modal/bottom-sheet/snackbar) go through `Navigator` + `OverplayComponentRegistry`.
|
|
47
|
+
|
|
48
|
+
## i18n / Localize (port of RN `Localize`)
|
|
49
|
+
|
|
50
|
+
- `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.
|
|
51
|
+
- 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.
|
|
52
|
+
- 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")`.
|
|
53
|
+
- 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.
|
|
54
|
+
- Some older components still do ad-hoc `AppLanguage.current` + `Map` lookups; new/changed code should use `LocalLocalize`.
|
|
55
|
+
|
|
56
|
+
## Code conventions
|
|
57
|
+
|
|
58
|
+
- **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)`).
|
|
59
|
+
- **Composable signatures:** required params first, slot lambdas next, `modifier: Modifier = Modifier` **last**; give optional params sensible defaults.
|
|
60
|
+
- **Stability:** annotate token/config data classes `@Stable`/`@Immutable`; memoize derived colors/styles/handlers with `remember(keys) { … }`.
|
|
61
|
+
- **Custom modifiers** are preferred: `conditional(...)`, `setAutomationId(...)`, the `clickable` variants in `modifier/`.
|
|
62
|
+
- Match the surrounding file's style when adding code.
|
|
63
|
+
|
|
64
|
+
## Writing docs in code (follow this)
|
|
65
|
+
|
|
66
|
+
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**:
|
|
67
|
+
|
|
68
|
+
- write KDoc walls or restate what the signature/code already says;
|
|
69
|
+
- narrate obvious steps or add section-banner noise;
|
|
70
|
+
- use a language other than English in code comments.
|
|
71
|
+
|
|
72
|
+
Prefer one tight line at the surprising spot over a paragraph. Match the (low) comment density already in the codebase.
|
|
73
|
+
|
|
74
|
+
## Gotchas
|
|
75
|
+
|
|
76
|
+
- **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.
|
|
77
|
+
- Prefer `NavigationContainer` over the deprecated `ApplicationContainer`; prefer `IMaxApi`/`LocalMaxApi` over the deprecated `PlatformApi`.
|
|
78
|
+
- iOS strings/maps must survive Kotlin/Native framework packaging — keep them compiled-in, not loaded from resource bundles.
|