@momo-kits/native-kits 0.163.1-sp.4-debug → 0.163.1-sp.5-debug

package/CLAUDE.md

@@ -53,6 +53,16 @@ Publishing is automated (`publish.sh` + GitLab CI on `[ci build]` / `main`). Do
 - 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`.
+
 ## 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)`).

package/compose/build.gradle.kts

@@ -40,7 +40,7 @@ kotlin {
     }
 
     cocoapods {
-        version = "0.163.1-sp.4-debug"
+        version = "0.163.1-sp.5-debug"
         summary = "IOS Shared module"
         homepage = "https://momo.vn"
         ios.deploymentTarget = "15.0"

package/compose/compose.podspec

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

package/gradle.properties

@@ -18,7 +18,7 @@ kotlin.apple.xcodeCompatibility.nowarn=true
 name="ComposeKits"
 group=vn.momo.kits
 artifact.id=kits
-version=0.163.1-sp.4
+version=0.163.1-sp.5
 
 repo=GitLab
 url=https://gitlab.mservice.com.vn/api/v4/projects/5400/packages/maven

package/ios/Application/ApplicationEnvironment.swift

@@ -38,10 +38,12 @@ public class KitConfig {
 }
 
 public class ApplicationEnvironment: ObservableObject {
-    let applicationContext: MiniAppContext?
-    let composeApi: KitComposeApi?
-    let config: KitConfig?
-    let maxApi: MaxApi?
+    // AI-GENERATED START: expose the host bridge to modules outside MoMoUIKits (e.g. the demo pod)
+    public let applicationContext: MiniAppContext?
+    public let composeApi: KitComposeApi?
+    public let config: KitConfig?
+    public let maxApi: MaxApi?
+    // AI-GENERATED END: expose the host bridge to modules outside MoMoUIKits (e.g. the demo pod)
 
     public init(applicationContext: MiniAppContext? = nil, composeApi: KitComposeApi? = nil, config: KitConfig? = nil, maxApi: MaxApi? = nil) {
         self.applicationContext = applicationContext

package/ios/Application/LanguageSource.swift

@@ -0,0 +1,93 @@
+// File: ios/Application/LanguageSource.swift
+// Created At: 2026-07-29 10:00:00 +07:00
+// Created By: AI
+// AI Agent: Claude Code
+// Model: claude-opus-5[1m]
+
+// AI-GENERATED START: observe the host app's active language so Localize can follow it
+import Foundation
+
+/// Read-only view of the host app's active language, plus change delivery.
+/// Values handed to `onChange` are already normalized to `Localize.VI` / `Localize.EN`.
+public protocol LanguageSource: AnyObject {
+    var currentLanguage: String { get }
+    /// `onChange` may be invoked on any thread; `Localize` dedupes and hops to main.
+    func startObserving(_ onChange: @escaping (String) -> Void)
+    func stopObserving()
+}
+
+/// Reads the language the MoMo host app persists in `UserDefaults`. All three host writers
+/// (the `RNResource` RN bridge, `JSONLocalization`, and the KMP `LocalizationProvider`) write the
+/// same key on `UserDefaults.standard` in-process, so KVO on it sees every one of them.
+public final class UserDefaultsLanguageSource: NSObject, LanguageSource {
+    public static let defaultKey = "language"
+
+    private let defaults: UserDefaults
+    private let key: String
+    private var onChange: ((String) -> Void)?
+    private var isObserving = false
+    private var kvoContext = 0
+
+    /// - Note: `key` must not contain `.` — `forKeyPath:` would read it as a key path.
+    public init(
+        defaults: UserDefaults = .standard,
+        key: String = UserDefaultsLanguageSource.defaultKey
+    ) {
+        self.defaults = defaults
+        self.key = key
+        super.init()
+    }
+
+    public var currentLanguage: String {
+        Localize.normalize(defaults.string(forKey: key))
+    }
+
+    public func startObserving(_ onChange: @escaping (String) -> Void) {
+        guard !isObserving else { return }
+        isObserving = true
+        self.onChange = onChange
+        defaults.addObserver(self, forKeyPath: key, options: [.new], context: &kvoContext)
+        // Safety net for writes KVO can miss (e.g. `removeObject`). Double delivery is free:
+        // `Localize` dedupes before touching `@Published`.
+        NotificationCenter.default.addObserver(
+            self,
+            selector: #selector(emit),
+            name: UserDefaults.didChangeNotification,
+            object: defaults
+        )
+    }
+
+    public func stopObserving() {
+        guard isObserving else { return }
+        isObserving = false
+        defaults.removeObserver(self, forKeyPath: key, context: &kvoContext)
+        NotificationCenter.default.removeObserver(
+            self,
+            name: UserDefaults.didChangeNotification,
+            object: defaults
+        )
+        onChange = nil
+    }
+
+    deinit {
+        stopObserving()
+    }
+
+    public override func observeValue(
+        forKeyPath keyPath: String?,
+        of object: Any?,
+        change: [NSKeyValueChangeKey: Any]?,
+        context: UnsafeMutableRawPointer?
+    ) {
+        guard context == &kvoContext else {
+            super.observeValue(forKeyPath: keyPath, of: object, change: change, context: context)
+            return
+        }
+        emit()
+    }
+
+    @objc private func emit() {
+        onChange?(currentLanguage)
+    }
+}
+// AI-GENERATED END: observe the host app's active language so Localize can follow it

package/ios/Application/Localize.swift

@@ -28,16 +28,69 @@ public final class Localize: ObservableObject {
     public static let VI = "vi"
     public static let EN = "en"
 
+    // AI-GENERATED START: follow the host app language and publish dictionary changes
+    /// App-wide instance bound to the host language; the environment default uses it too,
+    /// so every screen agrees on one language.
+    public static let shared = Localize()
+    // AI-GENERATED END: follow the host app language and publish dictionary changes
+
     private var assets: LocalizationObject
     @Published public private(set) var currentLanguage: String = Localize.VI
 
-    public init(_ translations: LocalizationObject = LocalizationObject()) {
+    // AI-GENERATED START: follow the host app language and publish dictionary changes
+    /// Bumped by `addTranslations` — `assets` is not published, so without this the dictionary
+    /// can change without any consumer re-rendering.
+    @Published public private(set) var revision: Int = 0
+
+    private let languageSource: LanguageSource?
+
+    /// `NavigationContainer` uses this to skip its legacy one-shot `MaxApi` pull.
+    var observesAppLanguage: Bool { languageSource != nil }
+
+    /// Pass `languageSource: nil` to opt out and keep the old "starts at vi" behavior.
+    public init(
+        _ translations: LocalizationObject = LocalizationObject(),
+        languageSource: LanguageSource? = UserDefaultsLanguageSource()
+    ) {
         self.assets = Localize.merge(base: Localize.defaultLanguage, override: translations)
+        self.languageSource = languageSource
+        guard let languageSource else { return }
+        // Seed synchronously so the first frame is already correct (no vi -> en flash).
+        currentLanguage = languageSource.currentLanguage
+        languageSource.startObserving { [weak self] language in self?.apply(language) }
+    }
+
+    deinit {
+        languageSource?.stopObserving()
+    }
+
+    /// Host values are sometimes legacy JSON-quoted (`"\"vi\""`); anything that is not `en` is `vi`.
+    public static func normalize(_ raw: String?) -> String {
+        let cleaned = (raw ?? "")
+            .replacingOccurrences(of: "\"", with: "")
+            .trimmingCharacters(in: .whitespacesAndNewlines)
+            .lowercased()
+        return cleaned == Localize.EN ? Localize.EN : Localize.VI
+    }
+
+    private func apply(_ language: String) {
+        // KVO and didChangeNotification both fire for one write; publish once, on main.
+        onMain {
+            guard self.currentLanguage != language else { return }
+            self.currentLanguage = language
+        }
+    }
+
+    /// Synchronous when already on main — an async hop would defer the switch by a frame.
+    private func onMain(_ work: @escaping () -> Void) {
+        if Thread.isMainThread { work() } else { DispatchQueue.main.async(execute: work) }
     }
 
+    /// A local override: the next host language change supersedes it.
     public func changeLanguage(_ language: String?) {
-        currentLanguage = (language == Localize.EN) ? Localize.EN : Localize.VI
+        apply(Localize.normalize(language))
     }
+    // AI-GENERATED END: follow the host app language and publish dictionary changes
 
     public func translate(_ key: String) -> String {
         let dictionary = currentLanguage == Localize.EN ? assets.en : assets.vi
@@ -58,6 +111,9 @@ public final class Localize: ObservableObject {
     /// Existing keys win (mirrors Compose: `merge(translations, assets)`).
     public func addTranslations(_ translations: LocalizationObject) {
         assets = Localize.merge(base: translations, override: assets)
+        // AI-GENERATED START: publish dictionary changes so consumers re-render
+        onMain { self.revision &+= 1 }
+        // AI-GENERATED END: publish dictionary changes so consumers re-render
     }
 
     private static func merge(base: LocalizationObject, override: LocalizationObject) -> LocalizationObject {
@@ -283,14 +339,22 @@ public final class Localize: ObservableObject {
 private struct LocalizeBox: Equatable {
     let localize: Localize
     let language: String
+    // AI-GENERATED START: invalidate consumers when the dictionary changes, not just the language
+    let revision: Int
+    // AI-GENERATED END: invalidate consumers when the dictionary changes, not just the language
 
     init(_ localize: Localize) {
         self.localize = localize
         self.language = localize.currentLanguage
+        // AI-GENERATED START: invalidate consumers when the dictionary changes, not just the language
+        self.revision = localize.revision
+        // AI-GENERATED END: invalidate consumers when the dictionary changes, not just the language
     }
 
     static func == (lhs: LocalizeBox, rhs: LocalizeBox) -> Bool {
-        lhs.localize === rhs.localize && lhs.language == rhs.language
+        // AI-GENERATED START: invalidate consumers when the dictionary changes, not just the language
+        lhs.localize === rhs.localize && lhs.language == rhs.language && lhs.revision == rhs.revision
+        // AI-GENERATED END: invalidate consumers when the dictionary changes, not just the language
     }
 }
 
@@ -298,7 +362,12 @@ private struct LocalizeKey: EnvironmentKey {
     /// A default-constructed `Localize` already carries the full kit dictionary, so a
     /// consumer that never injects one renders untranslated-but-correct text instead of
     /// trapping the way `@EnvironmentObject` does.
-    static let defaultValue = LocalizeBox(Localize())
+    // AI-GENERATED START: default to the app-language-observing shared instance
+    /// `defaultValue` is a `static let`, so this box is never rebuilt: without a provider the
+    /// language is right on first render but does not live-update. Wrap the root in
+    /// `.momoLocalize()` (or use `NavigationContainer`) to get updates.
+    static let defaultValue = LocalizeBox(Localize.shared)
+    // AI-GENERATED END: default to the app-language-observing shared instance
 }
 
 public extension EnvironmentValues {

package/ios/Application/LocalizeModifier.swift

@@ -0,0 +1,30 @@
+// File: ios/Application/LocalizeModifier.swift
+// Created At: 2026-07-29 10:00:00 +07:00
+// Created By: AI
+// AI Agent: Claude Code
+// Model: claude-opus-5[1m]
+
+// AI-GENERATED START: inject a language-observing Localize into any SwiftUI subtree
+import SwiftUI
+
+public extension View {
+    /// Injects an app-language-observing `Localize` and re-renders this subtree on change.
+    /// Use at every `UIHostingController` root that is not inside a `NavigationContainer`.
+    func momoLocalize(_ localize: Localize = .shared) -> some View {
+        modifier(MomoLocalizeModifier(localize: localize))
+    }
+}
+
+/// `@ObservedObject` is load-bearing: `@Environment(\.localize)` only invalidates when the boxed
+/// value changes, which requires *this* body to re-run on every publish. A plain helper that just
+/// set `\.localize` would inject a snapshot that never updates.
+private struct MomoLocalizeModifier: ViewModifier {
+    @ObservedObject var localize: Localize
+
+    func body(content: Content) -> some View {
+        content
+            .environmentObject(localize)
+            .environment(\.localize, localize)
+    }
+}
+// AI-GENERATED END: inject a language-observing Localize into any SwiftUI subtree

package/ios/Application/Navigation/NavigationContainer.swift

@@ -46,7 +46,9 @@ public struct NavigationContainer<Initial: View>: View {
                 maxApi: maxApi
             )
         )
-        _localize = StateObject(wrappedValue: localize ?? Localize())
+        // AI-GENERATED START: default to the app-language-observing shared Localize
+        _localize = StateObject(wrappedValue: localize ?? Localize.shared)
+        // AI-GENERATED END: default to the app-language-observing shared Localize
         self.composeApi = composeApi
         self.maxApi = maxApi
         self.setNavigator = setNavigator
@@ -62,15 +64,17 @@ public struct NavigationContainer<Initial: View>: View {
         .environmentObject(navigator)
         .environmentObject(applicationEnvironment)
         .environment(\.applicationEnvironment, applicationEnvironment)
-        .environmentObject(localize)
-        .environment(\.localize, localize)
+        // AI-GENERATED START: route Localize injection through the observing modifier
+        .momoLocalize(localize)
+        // AI-GENERATED END: route Localize injection through the observing modifier
         .fullScreenCover(item: $navigator.presented) { route in
             screenView(forDialog: route)
                 .environmentObject(navigator)
                 .environmentObject(applicationEnvironment)
                 .environment(\.applicationEnvironment, applicationEnvironment)
-                .environmentObject(localize)
-                .environment(\.localize, localize)
+                // AI-GENERATED START: route Localize injection through the observing modifier
+                .momoLocalize(localize)
+                // AI-GENERATED END: route Localize injection through the observing modifier
         }
         .overlay {
             if let item = navigator.overplay {
@@ -78,8 +82,9 @@ public struct NavigationContainer<Initial: View>: View {
                     .environmentObject(navigator)
                     .environmentObject(applicationEnvironment)
                     .environment(\.applicationEnvironment, applicationEnvironment)
-                    .environmentObject(localize)
-                    .environment(\.localize, localize)
+                    // AI-GENERATED START: route Localize injection through the observing modifier
+                    .momoLocalize(localize)
+                    // AI-GENERATED END: route Localize injection through the observing modifier
             }
         }
         .onAppear {
@@ -87,13 +92,15 @@ public struct NavigationContainer<Initial: View>: View {
                 navigator.composeApi = composeApi
             }
             setNavigator?(navigator)
-            // Mirrors Compose's LaunchedEffect(maxApi, resolvedLocalize): host-reported
-            // language wins over the default "vi" only when it resolves to English.
+            // AI-GENERATED START: demote the MaxApi language pull to a seed of last resort
+            // Only a seed: a Localize with a language source already tracks the host in both
+            // directions, so asking maxApi would just race it. `changeLanguage` normalizes the
+            // raw response and hops to main itself.
+            guard !localize.observesAppLanguage else { return }
             maxApi?.getLanguage { data in
-                if parseLanguage(data) == Localize.EN {
-                    localize.changeLanguage(Localize.EN)
-                }
+                localize.changeLanguage(data?["response"] as? String)
             }
+            // AI-GENERATED END: demote the MaxApi language pull to a seed of last resort
         }
     }
 
@@ -195,9 +202,3 @@ private func safeAreaBottomInset() -> CGFloat {
         .compactMap { ($0 as? UIWindowScene)?.keyWindow?.safeAreaInsets.bottom }
         .first ?? 0
 }
-
-private func parseLanguage(_ raw: [String: Any?]?) -> String? {
-    guard let response = (raw?["response"] as? String)?.trimmingCharacters(in: .whitespaces).lowercased(),
-          !response.isEmpty else { return nil }
-    return response.hasPrefix(Localize.EN) ? Localize.EN : Localize.VI
-}

package/ios/native-kits.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name             = 'MoMoUIKits'
-  s.version          = '0.163.1-sp.4'
+  s.version          = '0.163.1-sp.5'
   s.summary          = 'MoMoUIKits for iOS'
   s.homepage         = 'https://momo.vn'
   s.license          = { :type => 'MIT' }

package/ios-demo/MoMoUIKitsDemo.podspec

@@ -1,6 +1,6 @@
 Pod::Spec.new do |s|
   s.name             = 'MoMoUIKitsDemo'
-  s.version          = '0.163.1-sp.4'
+  s.version          = '0.163.1-sp.5'
   s.summary          = 'Demo browser for MoMoUIKits SwiftUI components'
   s.homepage         = 'https://momo.vn'
   s.license          = { :type => 'MIT' }

package/ios-demo/Sources/MoMoUIKitsDemo/SampleDemos/LocalizeDemo.swift

@@ -24,27 +24,72 @@ private let AppTranslations = LocalizationObject(
 )
 
 struct LocalizeDemo: View {
-    @EnvironmentObject private var localize: Localize
+    // AI-GENERATED START: observe the app language and drive it through the real platform API
+    @Environment(\.localize) private var localize
+    @Environment(\.applicationEnvironment) private var applicationEnvironment
+    // AI-GENERATED END: observe the app language and drive it through the real platform API
 
     private var isEnglish: Bool { localize.currentLanguage == Localize.EN }
 
+    // AI-GENERATED START: observe the app language and drive it through the real platform API
+    private var storedLanguage: String {
+        UserDefaults.standard.string(forKey: UserDefaultsLanguageSource.defaultKey) ?? "nil"
+    }
+
+    private func setLanguage(_ language: String) {
+        // Platform API -> KMP LanguageApi.SetLanguage -> LocalizationProvider.set, which also
+        // mirrors AppleLanguages. KVO then pushes the change back into Localize. The real wire.
+        if let composeApi = applicationEnvironment.composeApi {
+            _ = composeApi.request(funcName: "setLanguage", params: language)
+        } else {
+            localize.changeLanguage(language) // #Preview / sample app: no host bridge
+        }
+    }
+    // AI-GENERATED END: observe the app language and drive it through the real platform API
+
     var body: some View {
         ScrollView {
             VStack(alignment: .leading, spacing: 0) {
 
                 LocalizeSectionBox(title: "Đổi ngôn ngữ (toàn app)") {
                     MomoText(
-                        "localize.changeLanguage(...) đổi ngôn ngữ cho cả NavigationContainer — mọi màn hình đang đọc translate() sẽ cập nhật theo.",
+                        "Switch gọi platform API setLanguage — đổi ngôn ngữ THẬT của app. Localize observe lại "
+                            + "qua UserDefaults nên mọi màn hình đang đọc translate() đều cập nhật.",
                         typography: .descriptionDefaultRegular
                     )
                     Switch(
                         .constant(isEnglish),
-                        onChange: { _ in localize.changeLanguage(isEnglish ? Localize.VI : Localize.EN) },
+                        onChange: { _ in setLanguage(isEnglish ? Localize.VI : Localize.EN) },
                         title: "English"
                     )
                     MomoText("currentLanguage = \(localize.currentLanguage)", typography: .labelDefaultMedium)
                 }
 
+                // AI-GENERATED START: prove the observation loop, not kit-local state, drives updates
+                LocalizeSectionBox(title: "Nguồn thật: UserDefaults") {
+                    MomoText(
+                        "Ghi thẳng vào UserDefaults, bỏ qua mọi API của kit — màn hình vẫn đổi, chứng minh "
+                            + "Localize đang observe ngôn ngữ app.",
+                        typography: .descriptionDefaultRegular
+                    )
+                    TranslationRow(key: UserDefaultsLanguageSource.defaultKey, value: storedLanguage)
+                    Button(
+                        title: "Ghi thẳng UserDefaults = \"en\"",
+                        action: {
+                            // Quoted on purpose: proves normalize() strips the JSON quoting
+                            // RN and KMP persist.
+                            UserDefaults.standard.set(
+                                "\"en\"",
+                                forKey: UserDefaultsLanguageSource.defaultKey
+                            )
+                        },
+                        type: .outline,
+                        size: .medium,
+                        isFull: false
+                    )
+                }
+                // AI-GENERATED END: prove the observation loop, not kit-local state, drives updates
+
                 LocalizeSectionBox(title: "translate(key) — từ điển mặc định của kit") {
                     TranslationRow(key: "confirm", value: localize.translate("confirm"))
                     TranslationRow(key: "cancel", value: localize.translate("cancel"))
@@ -179,8 +224,10 @@ private struct TranslationRow: View {
 #Preview {
     if #available(iOS 16.0, *) {
         NavigationStack {
+            // AI-GENERATED START: preview needs the observing provider or the toggle will not update
             LocalizeDemo()
-                .environmentObject(Localize())
+                .momoLocalize(Localize())
+            // AI-GENERATED END: preview needs the observing provider or the toggle will not update
         }
     } else {
         // Fallback on earlier versions

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@momo-kits/native-kits",
-  "version": "0.163.1-sp.4-debug",
+  "version": "0.163.1-sp.5-debug",
   "private": false,
   "dependencies": {},
   "devDependencies": {},