@cometchat/skills 3.0.0 → 4.0.0

package/skills/cometchat-android-v6-kotlin-components/SKILL.md

@@ -0,0 +1,197 @@
+---
+name: cometchat-android-v6-kotlin-components
+description: "CometChat Android UIKit v6 Kotlin Views component catalog — all custom View chat UI components, their properties, styles, and usage"
+license: "MIT"
+compatibility: "Android 9.0+ (API 28); Kotlin 1.9+; com.cometchat:chatuikit-kotlin-android:6.x"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.1"
+  tags: "cometchat, android, kotlin-views, components, conversations, messages, users, groups, calls"
+---
+
+> **Companion skills:** cometchat-android-v6-compose-components (Compose equivalent), cometchat-android-v6-kotlin-theming, cometchat-android-v6-kotlin-customization, cometchat-android-v6-kotlin-placement
+
+## Purpose
+
+Complete catalog of all Kotlin Views components in CometChat UIKit v6. Each component is a custom `View` class in `com.cometchat.uikit.kotlin.presentation`.
+
+## Use this skill when
+
+- Adding a CometChat Views component to an Activity or Fragment
+- Looking up component properties and methods
+- Understanding which component to use for a specific chat feature
+- Finding the style class for a component
+
+## Do not use this skill when
+
+- Working with Compose components (use `cometchat-android-v6-compose-components`)
+- Customizing bubble rendering (use `cometchat-android-v6-kotlin-customization`)
+- Placing components in navigation (use `cometchat-android-v6-kotlin-placement`)
+
+## 1. Component Catalog
+
+### 1.1 List Components
+
+| Component | Package | Type | Purpose |
+|---|---|---|---|
+| `CometChatConversations` | `presentation.conversations.ui` | View | Recent conversations list |
+| `CometChatUsers` | `presentation.users.ui` | View | User list |
+| `CometChatGroups` | `presentation.groups.ui` | View | Group list |
+| `CometChatGroupMembers` | `presentation.groupmembers.ui` | View | Members of a group |
+| `CometChatCallLogs` | `presentation.calllogs.ui` | View | Call history |
+
+### 1.2 Messaging Components
+
+| Component | Package | Type | Purpose |
+|---|---|---|---|
+| `CometChatMessageList` | `presentation.messagelist.ui` | View | Message list with bubbles |
+| `CometChatMessageComposer` | `presentation.messagecomposer.ui` | View | Message input with attachments |
+| `CometChatMessageHeader` | `presentation.messageheader.ui` | View | Chat header (name, status, actions) |
+| `CometChatMessageInformation` | `presentation.messageinformation.ui` | View | Message delivery/read info |
+| `CometChatThreadHeader` | `presentation.threadheader.ui` | View | Thread parent message header |
+
+### 1.3 Call Components
+
+| Component | Package | Type | Purpose |
+|---|---|---|---|
+| `CometChatCallButtons` | `presentation.callbuttons` | View | Audio/video call buttons |
+| `CometChatIncomingCall` | `presentation.incomingcall` | View | Incoming call screen |
+| `CometChatOutgoingCall` | `presentation.outgoingcall` | View | Outgoing call screen |
+| `CometChatOngoingCall` | `presentation.ongoingcall.ui` | View | Active call screen |
+| `CometChatCallActivity` | `calls` | Activity | Activity wrapper for calls |
+
+### 1.4 Utility Components
+
+| Component | Package | Type | Purpose |
+|---|---|---|---|
+| `CometChatSearch` | `presentation.search.ui` | View | Global search |
+| `CometChatReactionList` | `presentation.reactionlist.ui` | View | Reaction details |
+| `CometChatEmojiKeyboard` | `presentation.emojikeyboard.ui` | View | Emoji picker |
+| `CometChatStickerKeyboard` | `presentation.stickerkeyboard.ui` | View | Sticker picker |
+| `CometChatFlagMessageDialog` | `presentation.report` | Dialog | Report/flag message |
+
+### 1.5 Shared Elements
+
+Located in `presentation.shared/`:
+
+- AI features: `aiconversationstarter/`, `aiconversationsummary/`, `aismartreplies/`
+- Base elements: `baseelements/`
+- Message bubble: `messagebubble/` (BubbleFactory, CometChatMessageBubble, InternalContentRenderer)
+- Dialog: `dialog/`
+- Media: `mediarecorder/`, `mediaselection/`, `mediaviewer/`, `inlineaudiorecorder/`
+- Message preview: `messagepreview/`
+- Moderation: `moderation/`
+- Permissions: `permission/`
+- Popup menu: `popupmenu/`
+- Reactions: `reaction/`
+- Receipts: `receipts/`
+- Search box: `searchbox/`
+- Shimmer: `shimmer/`
+- Status indicator: `statusindicator/`
+- Suggestion list: `suggestionlist/`
+- Toolbar: `toolbar/`
+- Typing indicator: `typingindicator/`
+
+### 1.6 Adapters
+
+List components use RecyclerView adapters:
+
+| Adapter | Component |
+|---|---|
+| `ConversationsAdapter` | `CometChatConversations` |
+| `MessageAdapter` | `CometChatMessageList` |
+| Group/User adapters in respective packages | `CometChatGroups`, `CometChatUsers` |
+
+## 2. Basic Usage Examples
+
+### 2.1 Conversations List in an Activity
+
+```kotlin
+import com.cometchat.uikit.kotlin.presentation.conversations.ui.CometChatConversations
+
+class ConversationsActivity : AppCompatActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+
+        val conversations = CometChatConversations(this)
+        conversations.setOnItemClick { conversation ->
+            // Navigate to chat
+        }
+        setContentView(conversations)
+    }
+}
+```
+
+### 2.2 Message List in XML Layout
+
+```xml
+<com.cometchat.uikit.kotlin.presentation.messagelist.ui.CometChatMessageList
+    android:id="@+id/messageList"
+    android:layout_width="match_parent"
+    android:layout_height="0dp"
+    android:layout_weight="1" />
+```
+
+```kotlin
+val messageList = findViewById<CometChatMessageList>(R.id.messageList)
+messageList.setUser(user)
+```
+
+### 2.3 Users List
+
+```kotlin
+val users = CometChatUsers(this)
+users.setOnItemClick { user ->
+    // Navigate to chat with user
+}
+setContentView(users)
+```
+
+### 2.4 Full Chat Screen
+
+```kotlin
+class MessagesActivity : AppCompatActivity() {
+    override fun onCreate(savedInstanceState: Bundle?) {
+        super.onCreate(savedInstanceState)
+        setContentView(R.layout.activity_messages)
+
+        val header = findViewById<CometChatMessageHeader>(R.id.messageHeader)
+        val messageList = findViewById<CometChatMessageList>(R.id.messageList)
+        val composer = findViewById<CometChatMessageComposer>(R.id.messageComposer)
+
+        header.setUser(user)
+        messageList.setUser(user)
+        composer.setUser(user)
+    }
+}
+```
+
+## 3. Style Classes
+
+Every component has a corresponding style class in its `style/` subpackage:
+
+| Component | Style Class |
+|---|---|
+| `CometChatConversations` | `CometChatConversationsStyle` |
+| `CometChatUsers` | `CometChatUsersStyle` |
+| `CometChatGroups` | `CometChatGroupsStyle` |
+| `CometChatGroupMembers` | `CometChatGroupMembersStyle` |
+| `CometChatMessageList` | `CometChatMessageListStyle` |
+| `CometChatMessageComposer` | `CometChatMessageComposerStyle` |
+| `CometChatMessageHeader` | `CometChatMessageHeaderStyle` |
+| `CometChatCallLogs` | `CometChatCallLogsStyle` |
+| `CometChatThreadHeader` | `CometChatThreadHeaderStyle` |
+
+Style classes resolve defaults from XML theme attributes and `CometChatTheme` singleton.
+
+## 4. ViewModel Integration
+
+Each component creates its own ViewModel internally via factories from `chatuikit-core`. ViewModels are shared with the Compose stack — the same `CometChatConversationsViewModel` powers both `CometChatConversations` (View) and `CometChatConversations` (@Composable).
+
+## Hard rules
+
+- Activity theme MUST inherit from `CometChatTheme.DayNight` (or `.Light` / `.Dark`) — `Theme.AppCompat.*`, `Theme.MaterialComponents.*.Bridge`, plain `Theme.MaterialComponents.*`, and `Theme.Material3.*` all crash at component inflation. See `cometchat-android-v6-kotlin-placement` "Activity theme" section.
+- Components create their own ViewModels internally — do NOT try to create or inject ViewModels manually
+- Use `setUser(user)` or `setGroup(group)` to configure messaging components — they need a target to load messages
+- For bubble customization, use `setBubbleFactories()` and `set*ViewProvider()` — see `cometchat-android-v6-kotlin-customization`

package/skills/cometchat-android-v6-kotlin-customization/SKILL.md

@@ -0,0 +1,268 @@
+---
+name: cometchat-android-v6-kotlin-customization
+description: "CometChat Android UIKit v6 Kotlin Views customization — BubbleFactory abstract class, BubbleViewProvider, style classes, and per-slot overrides"
+license: "MIT"
+compatibility: "Android 9.0+ (API 28); Kotlin 1.9+; com.cometchat:chatuikit-kotlin-android:6.x"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat, android, kotlin-views, customization, bubble-factory, bubble-view-provider, style"
+---
+
+> **Companion skills:** cometchat-android-v6-compose-customization (Compose equivalent), cometchat-android-v6-kotlin-components, cometchat-android-v6-kotlin-theming, cometchat-android-v6-extensions (DataSource layer), cometchat-android-v6-events
+
+## Purpose
+
+Customize CometChat Kotlin Views components — override message bubble rendering with BubbleFactory, use BubbleViewProvider for per-slot overrides, and apply style classes. This is the v6 replacement for v5's DataSource/ChatConfigurator pattern.
+
+## Use this skill when
+
+- Creating custom message bubble rendering for specific message types
+- Overriding individual bubble slots (avatar, header, footer, content, etc.)
+- Applying custom styles to components
+- Replacing the entire bubble layout for a message type
+
+## Do not use this skill when
+
+- Working with Compose customization (use `cometchat-android-v6-compose-customization`)
+- Changing theme colors globally (use `cometchat-android-v6-kotlin-theming`)
+- Extending the data layer (use `cometchat-android-v6-extensions`)
+
+## 1. BubbleFactory (Message Bubble Customization)
+
+`BubbleFactory` is an abstract class in `com.cometchat.uikit.kotlin.presentation.shared.messagebubble`. Each subclass handles a specific message type.
+
+### 1.1 Creating a Custom BubbleFactory
+
+```kotlin
+import com.cometchat.uikit.kotlin.presentation.shared.messagebubble.BubbleFactory
+import com.cometchat.chat.constants.CometChatConstants
+import com.cometchat.chat.models.BaseMessage
+import com.cometchat.uikit.core.constants.UIKitConstants.MessageBubbleAlignment
+
+class LocationBubbleFactory : BubbleFactory() {
+
+    override fun getCategory(): String = CometChatConstants.CATEGORY_CUSTOM
+    override fun getType(): String = "location"
+
+    override fun createContentView(context: Context): View {
+        // Called ONCE when ViewHolder is created — message NOT available here
+        return LocationMapView(context)
+    }
+
+    override fun bindContentView(
+        view: View,
+        message: BaseMessage,
+        alignment: MessageBubbleAlignment,
+        holder: RecyclerView.ViewHolder?,
+        position: Int
+    ) {
+        // Called EVERY TIME a message is displayed
+        val mapView = view as LocationMapView
+        val metadata = message.metadata
+        mapView.setLocation(
+            metadata?.optDouble("latitude") ?: 0.0,
+            metadata?.optDouble("longitude") ?: 0.0
+        )
+    }
+}
+```
+
+### 1.2 Registering BubbleFactories
+
+```kotlin
+val messageList = findViewById<CometChatMessageList>(R.id.messageList)
+messageList.setBubbleFactories(listOf(
+    LocationBubbleFactory(),
+    PaymentBubbleFactory()
+))
+```
+
+The list is converted to a map keyed by `"category_type"` internally.
+
+### 1.3 Complete Bubble Replacement
+
+Override `createBubbleView()` / `bindBubbleView()` to replace the ENTIRE bubble:
+
+```kotlin
+class CustomBubbleFactory : BubbleFactory() {
+    override fun getCategory(): String = "custom"
+    override fun getType(): String = "payment"
+
+    override fun createBubbleView(context: Context): View? {
+        // Return non-null to replace the entire CometChatMessageBubble
+        return PaymentCardView(context)
+    }
+
+    override fun bindBubbleView(
+        view: View,
+        message: BaseMessage,
+        alignment: MessageBubbleAlignment,
+        holder: RecyclerView.ViewHolder?,
+        position: Int
+    ) {
+        (view as PaymentCardView).bind(message)
+    }
+}
+```
+
+When `createBubbleView()` returns non-null, `createContentView()` and all other slot methods are ignored.
+
+### 1.4 Slot Methods
+
+All follow the create/bind pattern for RecyclerView efficiency:
+
+| Create Method | Bind Method | Slot |
+|---|---|---|
+| `createContentView(ctx): View` | `bindContentView(view, msg, align, holder, pos)` | Main content |
+| `createLeadingView(ctx): View?` | `bindLeadingView(view, msg, align)` | Avatar |
+| `createHeaderView(ctx): View?` | `bindHeaderView(view, msg, align)` | Sender name |
+| `createReplyView(ctx): View?` | `bindReplyView(view, msg, align)` | Reply preview |
+| `createBottomView(ctx): View?` | `bindBottomView(view, msg, align)` | Reactions |
+| `createStatusInfoView(ctx): View?` | `bindStatusInfoView(view, msg, align)` | Timestamp/receipts |
+| `createThreadView(ctx): View?` | `bindThreadView(view, msg, align)` | Thread indicator |
+| `createFooterView(ctx): View?` | `bindFooterView(view, msg, align)` | Footer |
+
+**Critical:** `create*()` methods are called when the ViewHolder is created — the message is NOT available. All message-specific logic goes in `bind*()`.
+
+### 1.5 Style Override
+
+```kotlin
+override fun getBubbleStyle(
+    message: BaseMessage,
+    alignment: MessageBubbleAlignment
+): CometChatMessageBubbleStyle? {
+    // Highest priority in the 3-tier style chain
+    return CometChatMessageBubbleStyle(/* custom style */)
+}
+```
+
+### 1.6 Lifecycle
+
+```kotlin
+override fun onViewRecycled(contentView: View) {
+    // Clean up resources (image loads, animations, media playback)
+}
+```
+
+### 1.7 Factory Key
+
+```kotlin
+// Get the factory key for a message
+val key = BubbleFactory.getFactoryKey(message) // "category_type" or "deleted"
+
+// Create a key manually
+val key = BubbleFactory.getKey("custom", "location") // "custom_location"
+```
+
+## 2. BubbleViewProvider (Per-Slot Overrides)
+
+`BubbleViewProvider` is a simpler interface for overriding individual slots across ALL message types.
+
+### 2.1 Interface
+
+```kotlin
+interface BubbleViewProvider {
+    fun createView(
+        context: Context,
+        message: BaseMessage,
+        alignment: MessageBubbleAlignment
+    ): View?
+
+    fun bindView(
+        view: View,
+        message: BaseMessage,
+        alignment: MessageBubbleAlignment
+    )
+}
+```
+
+### 2.2 Usage
+
+```kotlin
+val messageList = findViewById<CometChatMessageList>(R.id.messageList)
+
+// Custom avatar for all messages
+messageList.setLeadingViewProvider(object : BubbleViewProvider {
+    override fun createView(
+        context: Context,
+        message: BaseMessage,
+        alignment: MessageBubbleAlignment
+    ): View? {
+        return if (alignment == MessageBubbleAlignment.LEFT) {
+            ImageView(context).apply {
+                layoutParams = ViewGroup.LayoutParams(32.dp, 32.dp)
+            }
+        } else null
+    }
+
+    override fun bindView(
+        view: View,
+        message: BaseMessage,
+        alignment: MessageBubbleAlignment
+    ) {
+        (view as ImageView).load(message.sender?.avatar)
+    }
+})
+```
+
+### 2.3 All Provider Setters
+
+| Method | Slot |
+|---|---|
+| `setLeadingViewProvider(provider)` | Avatar |
+| `setHeaderViewProvider(provider)` | Sender name |
+| `setContentViewProvider(provider)` | Main content |
+| `setReplyViewProvider(provider)` | Reply preview |
+| `setBottomViewProvider(provider)` | Reactions |
+| `setStatusInfoViewProvider(provider)` | Timestamp/receipts |
+| `setThreadViewProvider(provider)` | Thread indicator |
+| `setFooterViewProvider(provider)` | Footer |
+
+### 2.4 Priority Order
+
+For each slot:
+1. Explicit `BubbleViewProvider` (highest priority)
+2. `BubbleFactory` slot method
+3. Internal default rendering
+
+## 3. Component-Level Customization
+
+### 3.1 Header/Footer Views on MessageList
+
+```kotlin
+// Custom header above the message list
+messageList.setHeaderView(myCustomHeaderView)
+
+// Custom footer below the message list
+messageList.setFooterView(myCustomFooterView)
+```
+
+### 3.2 Style Classes
+
+```kotlin
+// Style classes resolve from XML attrs and CometChatTheme singleton
+val style = CometChatMessageListStyle(/* properties */)
+messageList.setStyle(style)
+```
+
+## 4. v5 → v6 Migration
+
+| v5 Pattern | v6 Pattern |
+|---|---|
+| `ChatConfigurator.enable(decorator)` | `messageList.setBubbleFactories(listOf(...))` |
+| DataSource template methods | BubbleFactory slot methods |
+| Global decorator chain | Per-component factory registration |
+| No bubble replacement | `createBubbleView()` for complete replacement |
+| Theme-level styling only | Per-factory `getBubbleStyle()` |
+
+## Hard rules
+
+- BubbleFactory is an `abstract class` — extend it with `BubbleFactory()`
+- `create*()` methods are called WITHOUT a message — do NOT access message data in create methods
+- `bind*()` methods receive the message — all message-specific logic goes here
+- BubbleViewProvider overrides take precedence over BubbleFactory slot methods
+- For per-type content customization, use BubbleFactory. For cross-type slot overrides, use BubbleViewProvider
+- `onViewRecycled()` is critical for cleaning up image loads, animations, or media playback
+- Do NOT confuse BubbleFactory (UI rendering) with DataSource (data fetching) — they are separate layers