@cometchat/skills 4.4.1 → 5.0.0

package/skills/cometchat-ios-core/references/swiftui.md

@@ -0,0 +1,91 @@
+# SwiftUI, and where `init → login` actually goes
+
+The kit is **UIKit-only**: every component is a `UIView`/`UIViewController`. It works in a SwiftUI
+app, but nothing about that is automatic, and the golden path in `SKILL.md` shows the code without
+saying where it lives. This file says where.
+
+> Verified on 5.1.22 by building and running a SwiftUI app from scratch: login succeeded and
+> `CometChatConversations` rendered with live data.
+
+## Where init and login go
+
+`init → login` must complete **before** any component renders, and it must run **once** for the
+process — not per view. SwiftUI views are values and their bodies re-evaluate freely, so a `.task`
+or `.onAppear` on a view is the wrong home for it.
+
+| lifecycle | put `init → login` in |
+|---|---|
+| **UIKit** (`AppDelegate` + `SceneDelegate`) | `application(_:didFinishLaunchingWithOptions:)` |
+| **SwiftUI** (`@main struct App`) | an `AppDelegate` attached with `@UIApplicationDelegateAdaptor` |
+
+A stock Xcode project today has **no `AppDelegate` and no `SceneDelegate`** — it is a SwiftUI
+`App`. Adding the adaptor is how you get a launch hook back.
+
+```swift
+final class AppDelegate: NSObject, UIApplicationDelegate {
+    func application(_ app: UIApplication,
+                     didFinishLaunchingWithOptions opts: [UIApplication.LaunchOptionsKey: Any]? = nil) -> Bool {
+        CometChatUIKit.initFromSettings { _, _ in                    // attribution — see setup-credentials §6
+            CometChatUIKit.init(uiKitSettings: settings) { result in
+                if case .success = result {
+                    CometChatUIKit.login(uid: uid) { _ in
+                        DispatchQueue.main.async { AppState.shared.ready = true }
+                    }
+                }
+            }
+        }
+        return true
+    }
+}
+
+@main
+struct MyApp: App {
+    @UIApplicationDelegateAdaptor(AppDelegate.self) var delegate
+    @ObservedObject private var state = AppState.shared
+    var body: some Scene {
+        WindowGroup {
+            if state.ready { ChatScreen() }        // render ONLY after login resolves
+            else { ProgressView() }
+        }
+    }
+}
+```
+
+`AppState` is any `ObservableObject` with a `ready` flag. Gating on it is not optional: rendering a
+component before login resolves is the silent-failure case the ordering rule exists to prevent.
+
+## Showing a UIKit component from SwiftUI
+
+Wrap it in `UIViewControllerRepresentable`. Wrap it in a `UINavigationController` too — the kit
+composes by navigation (list pushes the message pane), so without one the push has nowhere to go.
+
+```swift
+struct ConversationsView: UIViewControllerRepresentable {
+    func makeUIViewController(context: Context) -> UINavigationController {
+        let list = CometChatConversations()
+        // wire onItemClick here exactly as in the golden path
+        return UINavigationController(rootViewController: list)
+    }
+    func updateUIViewController(_ vc: UINavigationController, context: Context) {}
+}
+```
+
+**Qualify `CometChatSDK.User` / `CometChatSDK.Group` in any file that imports SwiftUI.** SwiftUI
+declares its own `Group`, so a bare `as? Group` is `'Group' is ambiguous for type lookup` — a
+guaranteed compile error in the wrapper file this page tells you to write. A live test hit exactly
+that. Host apps also very often define their own `User` model, so qualify both:
+
+```swift
+vc.user  = conversation.conversationWith as? CometChatSDK.User
+vc.group = conversation.conversationWith as? CometChatSDK.Group
+```
+
+The golden path in `SKILL.md` and the recipe in `layout.md` are already written this way; keep them
+qualified rather than "tidying" the module prefix away.
+
+`NavigationStack` does **not** substitute for this. The kit pushes with
+`UINavigationController.pushViewController`, which a SwiftUI `NavigationStack` does not provide.
+
+Rule 5 still applies inside that navigation controller — see `layout.md`. The coordinator goes on
+the `UINavigationController` you create in `makeUIViewController`, and something must hold it: the
+`delegate` is weak, and a coordinator created inline is deallocated immediately.

package/skills/cometchat-ios-core/references/troubleshooting.md

@@ -0,0 +1,100 @@
+# Troubleshooting — symptom → cause → fix
+
+Every entry here is a RUNTIME failure that compiled cleanly. That is the character of this kit:
+the compiler will not catch composition mistakes.
+
+## Blank screen, nothing renders
+
+**Cause:** `login()` ran before `init()` finished, or it failed and nothing surfaced the error.
+`login()` called early fails SILENTLY.
+
+**Fix:** nest them — never sequence with a timer. Render only after login succeeds:
+
+```swift
+CometChatUIKit.init(uiKitSettings: settings) { result in
+    switch result {
+    case .success:
+        CometChatUIKit.login(uid: uid) { loginResult in
+            switch loginResult {
+            case .success:            DispatchQueue.main.async { mountChat() }
+            case .onError(let e):     print("login failed:", e.errorDescription)
+            @unknown default:         break
+            }
+        }
+    case .failure(let e): print("init failed:", e.localizedDescription)
+    }
+}
+```
+
+Also check credentials actually resolved — an unsubstituted xcconfig value arrives as the
+literal `$(COMETCHAT_APP_ID)`, not nil (see `setup-credentials.md`).
+
+## The list renders but tapping a row does nothing
+
+**Cause:** `set(onItemClick:)` was never wired. The rows are real; the destination is not.
+
+**Fix:** push the message screen from the click handler, taking exactly one of user/group —
+see `layout.md`.
+
+## Tapping the composer makes the conversation disappear
+
+**Cause:** the composer is pinned to `view.keyboardLayoutGuide.topAnchor`. The kit's composer
+already adjusts for the keyboard, so this double-applies it — the message list collapses to height
+0 and the composer's own text field goes with it, leaving only the attachment/mic/send icons
+jammed under the header.
+
+**Fix:** pin the composer to `view.safeAreaLayoutGuide.bottomAnchor`, as the published recipe
+shows. The kit handles the keyboard from there.
+
+## Two navigation bars stacked on the message screen
+
+**Cause:** `CometChatMessageHeader` carries its own title and back control, and the
+`UINavigationController` bar is still visible above it.
+
+**Fix:** hide the nav bar on the message screen in `viewDidLoad`, restore it in
+`viewWillDisappear`. Do not hide it globally.
+
+## The message pane is a thin strip / everything is squashed at the top
+
+**Cause:** the list is not pinned both top AND bottom, so it sizes to its intrinsic content
+instead of filling the space between header and composer.
+
+**Fix:** add both constraints (Rule 4 in `layout.md`). Verify by opening a conversation, not by
+looking at the list screen — the collapse is only visible on the pushed screen.
+
+## An empty list that might be an error
+
+**Cause:** no `set(onError:)`, so a failed fetch looks exactly like an empty account.
+
+**Fix:** wire `set(onError:)` on every list component and surface the failure.
+
+## Replies render but never send
+
+**Cause:** the thread's parent was set through two different APIs — see `anti-patterns.md` §4.
+
+**Fix:** set the parent one way, per the docs for that component, then actually send a reply to
+confirm.
+
+## Link errors / missing symbols after adding the package
+
+**Cause:** `CometChatSDK` is not pinned to the exact version the binary kit was compiled
+against, or (on 5.1.19) `CometChatCallsSDK` is absent — the shipped interface hard-imports it,
+so even a chat-only app fails to compile without it.
+
+**Fix:** pin both exactly. See `anti-patterns.md` §5.
+
+## The group-members screen cannot be dismissed
+
+**Symptom:** you push `CometChatGroupMembers`, it renders correctly, and then there is no way back
+— the kit's Cancel control does nothing, a wired `set(onBack:)` never fires, and edge-swipe back is
+inert.
+
+**Status: reported and NOT reproduced by us.** An acceptance pass measured it (Cancel
+`action=didTapBackButton` inert across 3 taps, `set(onBack:)` instrumented and never called); an
+attempt to reproduce it in the review harness did not get far enough to confirm or refute. So there
+is no verified fix here, and none is invented: we do not know whether the fault is the recipe or
+the kit.
+
+**What to do:** treat "can the user leave this screen?" as a test you run, not a property you
+assume. If you hit it, give yourself a dismissal path you control — your own bar button, or
+presenting rather than pushing — and please report the exact flow so this can be pinned down.