@cometchat/skills 3.0.0 → 4.0.0

package/skills/cometchat-ios-customization/SKILL.md

@@ -0,0 +1,825 @@
+---
+name: cometchat-ios-customization
+description: "Customize CometChat iOS UI Kit beyond theming — custom views, message templates, text formatters, and event handling."
+license: "MIT"
+compatibility: "CometChatUIKitSwift ^5; iOS 13+"
+allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "chat cometchat ios customization templates formatters events"
+---
+
+## Purpose
+
+This skill teaches advanced customization of CometChat iOS UI Kit — custom views, message templates, text formatters, event listeners, and request builder filters.
+
+---
+
+## 1. Custom Views in CometChatConversations
+
+### Custom List Item View
+
+Replace the entire list item with a custom view:
+
+```swift
+let conversations = CometChatConversations()
+
+conversations.set(listItemView: { (conversation: Conversation) -> UIView in
+    let customView = UIView()
+    customView.backgroundColor = .secondarySystemBackground
+    
+    let nameLabel = UILabel()
+    nameLabel.font = .boldSystemFont(ofSize: 16)
+    
+    if let user = conversation.conversationWith as? User {
+        nameLabel.text = user.name
+    } else if let group = conversation.conversationWith as? Group {
+        nameLabel.text = group.name
+    }
+    
+    customView.addSubview(nameLabel)
+    nameLabel.translatesAutoresizingMaskIntoConstraints = false
+    NSLayoutConstraint.activate([
+        nameLabel.leadingAnchor.constraint(equalTo: customView.leadingAnchor, constant: 16),
+        nameLabel.centerYAnchor.constraint(equalTo: customView.centerYAnchor)
+    ])
+    
+    return customView
+})
+```
+
+### Custom Leading View (Avatar Area)
+
+```swift
+conversations.set(leadingView: { (conversation: Conversation) -> UIView in
+    let avatarView = UIView()
+    avatarView.backgroundColor = .systemBlue
+    avatarView.layer.cornerRadius = 24
+    
+    let initialsLabel = UILabel()
+    initialsLabel.textColor = .white
+    initialsLabel.font = .boldSystemFont(ofSize: 14)
+    initialsLabel.textAlignment = .center
+    
+    if let user = conversation.conversationWith as? User {
+        initialsLabel.text = String(user.name?.prefix(2).uppercased() ?? "")
+    } else if let group = conversation.conversationWith as? Group {
+        initialsLabel.text = String(group.name?.prefix(2).uppercased() ?? "")
+    }
+    
+    avatarView.addSubview(initialsLabel)
+    initialsLabel.translatesAutoresizingMaskIntoConstraints = false
+    NSLayoutConstraint.activate([
+        initialsLabel.centerXAnchor.constraint(equalTo: avatarView.centerXAnchor),
+        initialsLabel.centerYAnchor.constraint(equalTo: avatarView.centerYAnchor),
+        avatarView.widthAnchor.constraint(equalToConstant: 48),
+        avatarView.heightAnchor.constraint(equalToConstant: 48)
+    ])
+    
+    return avatarView
+})
+```
+
+### Custom Title View
+
+```swift
+conversations.set(titleView: { (conversation: Conversation) -> UIView in
+    let stackView = UIStackView()
+    stackView.axis = .horizontal
+    stackView.spacing = 8
+    
+    let nameLabel = UILabel()
+    nameLabel.font = .boldSystemFont(ofSize: 16)
+    
+    let verifiedBadge = UIImageView(image: UIImage(systemName: "checkmark.seal.fill"))
+    verifiedBadge.tintColor = .systemBlue
+    verifiedBadge.isHidden = true
+    
+    if let user = conversation.conversationWith as? User {
+        nameLabel.text = user.name
+        // Show badge for verified users (custom metadata)
+        if let metadata = user.metadata, metadata["verified"] as? Bool == true {
+            verifiedBadge.isHidden = false
+        }
+    } else if let group = conversation.conversationWith as? Group {
+        nameLabel.text = group.name
+    }
+    
+    stackView.addArrangedSubview(nameLabel)
+    stackView.addArrangedSubview(verifiedBadge)
+    
+    return stackView
+})
+```
+
+### Custom Subtitle View
+
+```swift
+conversations.set(subtitleView: { (conversation: Conversation) -> UIView in
+    let label = UILabel()
+    label.font = .systemFont(ofSize: 14)
+    label.textColor = .secondaryLabel
+    
+    if let lastMessage = conversation.lastMessage as? TextMessage {
+        label.text = lastMessage.text
+    } else if let lastMessage = conversation.lastMessage as? MediaMessage {
+        switch lastMessage.messageType {
+        case .image:
+            label.text = "📷 Photo"
+        case .video:
+            label.text = "🎥 Video"
+        case .audio:
+            label.text = "🎵 Audio"
+        case .file:
+            label.text = "📎 File"
+        default:
+            label.text = "Attachment"
+        }
+    } else {
+        label.text = "No messages yet"
+    }
+    
+    return label
+})
+```
+
+### Custom Tail View
+
+```swift
+conversations.set(trailView: { (conversation: Conversation) -> UIView in
+    let stackView = UIStackView()
+    stackView.axis = .vertical
+    stackView.alignment = .trailing
+    stackView.spacing = 4
+    
+    // Time label
+    let timeLabel = UILabel()
+    timeLabel.font = .systemFont(ofSize: 12)
+    timeLabel.textColor = .tertiaryLabel
+    
+    if let timestamp = conversation.lastMessage?.sentAt {
+        let date = Date(timeIntervalSince1970: TimeInterval(timestamp))
+        let formatter = DateFormatter()
+        formatter.dateFormat = "h:mm a"
+        timeLabel.text = formatter.string(from: date)
+    }
+    
+    // Unread badge
+    let badge = UILabel()
+    badge.font = .boldSystemFont(ofSize: 12)
+    badge.textColor = .white
+    badge.backgroundColor = .systemBlue
+    badge.textAlignment = .center
+    badge.layer.cornerRadius = 10
+    badge.clipsToBounds = true
+    
+    let unreadCount = conversation.unreadMessageCount
+    badge.isHidden = unreadCount == 0
+    badge.text = unreadCount > 99 ? "99+" : "\(unreadCount)"
+    
+    stackView.addArrangedSubview(timeLabel)
+    stackView.addArrangedSubview(badge)
+    
+    NSLayoutConstraint.activate([
+        badge.widthAnchor.constraint(greaterThanOrEqualToConstant: 20),
+        badge.heightAnchor.constraint(equalToConstant: 20)
+    ])
+    
+    return stackView
+})
+```
+
+---
+
+## 2. Custom Swipe Actions
+
+### Custom Options
+
+```swift
+conversations.set(options: { (conversation: Conversation?) -> [CometChatConversationOption] in
+    guard let conversation = conversation else { return [] }
+    var options: [CometChatConversationOption] = []
+    
+    // Pin conversation
+    let pinOption = CometChatConversationOption(
+        id: "pin",
+        title: "Pin",
+        icon: UIImage(systemName: "pin.fill"),
+        backgroundColor: .systemYellow,
+        iconTint: .white
+    )
+    pinOption.onClick = { _, _, _, _ in
+        // Handle pin action
+        print("Pin conversation: \(conversation.conversationId ?? "")")
+    }
+    options.append(pinOption)
+    
+    // Mute conversation
+    let muteOption = CometChatConversationOption(
+        id: "mute",
+        title: "Mute",
+        icon: UIImage(systemName: "bell.slash.fill"),
+        backgroundColor: .systemGray,
+        iconTint: .white
+    )
+    muteOption.onClick = { _, _, _, _ in
+        // Handle mute action
+        print("Mute conversation: \(conversation.conversationId ?? "")")
+    }
+    options.append(muteOption)
+    
+    // Delete conversation
+    let deleteOption = CometChatConversationOption(
+        id: "delete",
+        title: "Delete",
+        icon: UIImage(systemName: "trash.fill"),
+        backgroundColor: .systemRed,
+        iconTint: .white
+    )
+    deleteOption.onClick = { _, _, _, _ in
+        // Handle delete action
+        print("Delete conversation: \(conversation.conversationId ?? "")")
+    }
+    options.append(deleteOption)
+    
+    return options
+})
+```
+
+### Add Options (Keep Default + Add Custom)
+
+```swift
+conversations.add(options: { (conversation: Conversation?) -> [CometChatConversationOption] in
+    let archiveOption = CometChatConversationOption(
+        id: "archive",
+        title: "Archive",
+        icon: UIImage(systemName: "archivebox.fill"),
+        backgroundColor: .systemPurple,
+        iconTint: .white
+    )
+    archiveOption.onClick = { _, _, _, _ in
+        print("Archive conversation")
+    }
+    
+    return [archiveOption]
+})
+```
+
+---
+
+## 3. Custom Message Templates
+
+### Creating a Custom Message Template
+
+```swift
+let messageList = CometChatMessageList()
+
+// Get default templates
+var templates = CometChatUIKit.getDataSource().getAllMessageTemplates()
+
+// Create custom template for a specific message type
+let customTemplate = CometChatMessageTemplate(
+    type: "custom_poll",
+    category: "custom"
+)
+
+// Custom content view
+customTemplate.contentView = { message, alignment, controller in
+    guard let customMessage = message as? CustomMessage,
+          let data = customMessage.customData else {
+        return UIView()
+    }
+    
+    let pollView = PollBubbleView()
+    pollView.configure(with: data)
+    return pollView
+}
+
+// Custom header view (above the bubble)
+customTemplate.headerView = { message, alignment, controller in
+    let label = UILabel()
+    label.text = "📊 Poll"
+    label.font = .boldSystemFont(ofSize: 12)
+    label.textColor = .secondaryLabel
+    return label
+}
+
+// Custom footer view (below the bubble)
+customTemplate.footerView = { message, alignment, controller in
+    let label = UILabel()
+    label.text = "Tap to vote"
+    label.font = .systemFont(ofSize: 11)
+    label.textColor = .tertiaryLabel
+    return label
+}
+
+// Custom bubble view (wraps content)
+customTemplate.bubbleView = { message, alignment, controller in
+    let bubble = UIView()
+    bubble.backgroundColor = alignment == .right 
+        ? CometChatTheme.primaryColor.withAlphaComponent(0.1)
+        : UIColor.secondarySystemBackground
+    bubble.layer.cornerRadius = 12
+    return bubble
+}
+
+// Custom options (long press menu)
+customTemplate.options = { message, group, controller in
+    let viewResultsOption = CometChatMessageOption(
+        id: "view_results",
+        title: "View Results",
+        icon: UIImage(systemName: "chart.bar.fill")
+    )
+    viewResultsOption.onClick = { _, _, _, _ in
+        // Show poll results
+    }
+    
+    return [viewResultsOption]
+}
+
+templates.append(customTemplate)
+messageList.set(templates: templates)
+```
+
+### Custom Poll Bubble View Example
+
+```swift
+class PollBubbleView: UIView {
+    
+    private let questionLabel = UILabel()
+    private let optionsStack = UIStackView()
+    
+    override init(frame: CGRect) {
+        super.init(frame: frame)
+        setupUI()
+    }
+    
+    required init?(coder: NSCoder) {
+        super.init(coder: coder)
+        setupUI()
+    }
+    
+    private func setupUI() {
+        questionLabel.font = .boldSystemFont(ofSize: 16)
+        questionLabel.numberOfLines = 0
+        
+        optionsStack.axis = .vertical
+        optionsStack.spacing = 8
+        
+        addSubview(questionLabel)
+        addSubview(optionsStack)
+        
+        questionLabel.translatesAutoresizingMaskIntoConstraints = false
+        optionsStack.translatesAutoresizingMaskIntoConstraints = false
+        
+        NSLayoutConstraint.activate([
+            questionLabel.topAnchor.constraint(equalTo: topAnchor, constant: 12),
+            questionLabel.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 12),
+            questionLabel.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -12),
+            
+            optionsStack.topAnchor.constraint(equalTo: questionLabel.bottomAnchor, constant: 12),
+            optionsStack.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 12),
+            optionsStack.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -12),
+            optionsStack.bottomAnchor.constraint(equalTo: bottomAnchor, constant: -12)
+        ])
+    }
+    
+    func configure(with data: [String: Any]) {
+        questionLabel.text = data["question"] as? String
+        
+        optionsStack.arrangedSubviews.forEach { $0.removeFromSuperview() }
+        
+        if let options = data["options"] as? [String] {
+            for option in options {
+                let button = UIButton(type: .system)
+                button.setTitle(option, for: .normal)
+                button.backgroundColor = .systemGray5
+                button.layer.cornerRadius = 8
+                button.contentEdgeInsets = UIEdgeInsets(top: 8, left: 12, bottom: 8, right: 12)
+                optionsStack.addArrangedSubview(button)
+            }
+        }
+    }
+}
+```
+
+---
+
+## 4. Text Formatters
+
+### Creating a Custom Text Formatter
+
+```swift
+class HashtagFormatter: CometChatTextFormatter {
+    
+    override func getRegex() -> String {
+        return "#[a-zA-Z0-9_]+"
+    }
+    
+    override func prepareMessageString(
+        baseMessage: BaseMessage,
+        regexString: String,
+        alignment: MessageBubbleAlignment,
+        formattingType: FormattingType
+    ) -> NSAttributedString {
+        
+        guard let textMessage = baseMessage as? TextMessage,
+              let text = textMessage.text else {
+            return NSAttributedString()
+        }
+        
+        let attributedString = NSMutableAttributedString(string: text)
+        
+        // Default text attributes
+        let defaultAttributes: [NSAttributedString.Key: Any] = [
+            .font: CometChatTypography.Body.regular,
+            .foregroundColor: alignment == .right ? UIColor.white : UIColor.label
+        ]
+        attributedString.addAttributes(defaultAttributes, range: NSRange(location: 0, length: text.count))
+        
+        // Highlight hashtags
+        let regex = try? NSRegularExpression(pattern: regexString, options: [])
+        let matches = regex?.matches(in: text, options: [], range: NSRange(location: 0, length: text.count)) ?? []
+        
+        for match in matches {
+            let hashtagAttributes: [NSAttributedString.Key: Any] = [
+                .foregroundColor: UIColor.systemBlue,
+                .font: CometChatTypography.Body.medium
+            ]
+            attributedString.addAttributes(hashtagAttributes, range: match.range)
+        }
+        
+        return attributedString
+    }
+    
+    override func onTextTapped(
+        baseMessage: BaseMessage,
+        tappedText: String,
+        controller: UIViewController?
+    ) {
+        // Handle hashtag tap
+        print("Hashtag tapped: \(tappedText)")
+        // Navigate to hashtag search, etc.
+    }
+}
+
+// Usage
+let messageList = CometChatMessageList()
+messageList.textFormatter = [
+    CometChatMentionsFormatter(),  // Built-in mentions
+    HashtagFormatter()              // Custom hashtags
+]
+```
+
+### URL Formatter with Custom Preview
+
+```swift
+class CustomURLFormatter: CometChatTextFormatter {
+    
+    override func getRegex() -> String {
+        return "https?://[^\\s]+"
+    }
+    
+    override func prepareMessageString(
+        baseMessage: BaseMessage,
+        regexString: String,
+        alignment: MessageBubbleAlignment,
+        formattingType: FormattingType
+    ) -> NSAttributedString {
+        
+        guard let textMessage = baseMessage as? TextMessage,
+              let text = textMessage.text else {
+            return NSAttributedString()
+        }
+        
+        let attributedString = NSMutableAttributedString(string: text)
+        
+        let regex = try? NSRegularExpression(pattern: regexString, options: [])
+        let matches = regex?.matches(in: text, options: [], range: NSRange(location: 0, length: text.count)) ?? []
+        
+        for match in matches {
+            let urlAttributes: [NSAttributedString.Key: Any] = [
+                .foregroundColor: UIColor.systemBlue,
+                .underlineStyle: NSUnderlineStyle.single.rawValue
+            ]
+            attributedString.addAttributes(urlAttributes, range: match.range)
+        }
+        
+        return attributedString
+    }
+    
+    override func onTextTapped(
+        baseMessage: BaseMessage,
+        tappedText: String,
+        controller: UIViewController?
+    ) {
+        if let url = URL(string: tappedText) {
+            UIApplication.shared.open(url)
+        }
+    }
+}
+```
+
+---
+
+## 5. Event Listeners
+
+### Message Events
+
+```swift
+import CometChatSDK
+
+class MessageEventListener: CometChatMessageEventListener {
+    
+    func ccMessageSent(message: BaseMessage, status: MessageStatus) {
+        switch status {
+        case .inProgress:
+            print("Message sending...")
+        case .success:
+            print("Message sent successfully")
+        case .error:
+            print("Message failed to send")
+        }
+    }
+    
+    func ccMessageEdited(message: BaseMessage, status: MessageStatus) {
+        print("Message edited: \(message.id)")
+    }
+    
+    func ccMessageDeleted(message: BaseMessage) {
+        print("Message deleted: \(message.id)")
+    }
+    
+    func ccMessageRead(message: BaseMessage) {
+        print("Message read: \(message.id)")
+    }
+    
+    func ccLiveReaction(reaction: TransientMessage) {
+        print("Live reaction received")
+    }
+}
+
+// Register listener
+let listener = MessageEventListener()
+CometChatMessageEvents.addListener("message-listener", listener)
+
+// Remove listener when done
+CometChatMessageEvents.removeListener("message-listener")
+```
+
+### User Events
+
+```swift
+class UserEventListener: CometChatUserEventListener {
+    
+    func ccUserBlocked(user: User) {
+        print("User blocked: \(user.name ?? "")")
+    }
+    
+    func ccUserUnblocked(user: User) {
+        print("User unblocked: \(user.name ?? "")")
+    }
+}
+
+// Register
+CometChatUserEvents.addListener("user-listener", UserEventListener())
+```
+
+### Group Events
+
+```swift
+class GroupEventListener: CometChatGroupEventListener {
+    
+    func ccGroupCreated(group: Group) {
+        print("Group created: \(group.name ?? "")")
+    }
+    
+    func ccGroupDeleted(group: Group) {
+        print("Group deleted: \(group.name ?? "")")
+    }
+    
+    func ccGroupMemberAdded(messages: [ActionMessage], usersAdded: [User], groupAddedIn: Group, addedBy: User) {
+        print("Members added to group")
+    }
+    
+    func ccGroupMemberKicked(message: ActionMessage, kickedUser: User, kickedBy: User, kickedFrom: Group) {
+        print("Member kicked from group")
+    }
+    
+    func ccGroupMemberBanned(message: ActionMessage, bannedUser: User, bannedBy: User, bannedFrom: Group) {
+        print("Member banned from group")
+    }
+    
+    func ccOwnershipChanged(group: Group, newOwner: GroupMember) {
+        print("Group ownership changed")
+    }
+}
+
+// Register
+CometChatGroupEvents.addListener("group-listener", GroupEventListener())
+```
+
+### Call Events
+
+```swift
+class CallEventListener: CometChatCallEventListener {
+    
+    func ccCallAccepted(call: Call) {
+        print("Call accepted")
+    }
+    
+    func ccCallRejected(call: Call) {
+        print("Call rejected")
+    }
+    
+    func ccCallEnded(call: Call) {
+        print("Call ended")
+    }
+    
+    func ccOutgoingCall(call: Call) {
+        print("Outgoing call initiated")
+    }
+    
+    func ccCallInitiated(call: Call) {
+        print("Call initiated")
+    }
+}
+
+// Register
+CometChatCallEvents.addListener("call-listener", CallEventListener())
+```
+
+---
+
+## 6. Request Builder Filters
+
+### Filter Conversations
+
+```swift
+let conversations = CometChatConversations()
+
+// Only show user conversations (no groups)
+conversations.set(conversationsRequestBuilder: ConversationsRequest.ConversationsRequestBuilder()
+    .set(conversationType: .user)
+    .set(limit: 30)
+)
+
+// Only show conversations with specific tags
+conversations.set(conversationsRequestBuilder: ConversationsRequest.ConversationsRequestBuilder()
+    .set(tags: ["vip", "premium"])
+    .set(limit: 30)
+)
+```
+
+### Filter Messages
+
+```swift
+let messageList = CometChatMessageList()
+
+// Only show text and image messages
+messageList.set(messagesRequestBuilder: MessagesRequest.MessageRequestBuilder()
+    .set(uid: user.uid ?? "")
+    .set(types: [CometChatConstants.MessageType.text, CometChatConstants.MessageType.image])
+    .set(limit: 30)
+)
+
+// Only show messages from a specific time range
+let startDate = Calendar.current.date(byAdding: .day, value: -7, to: Date())!
+messageList.set(messagesRequestBuilder: MessagesRequest.MessageRequestBuilder()
+    .set(uid: user.uid ?? "")
+    .set(timestamp: Int(startDate.timeIntervalSince1970))
+    .set(limit: 50)
+)
+
+// Hide deleted messages
+messageList.set(messagesRequestBuilder: MessagesRequest.MessageRequestBuilder()
+    .set(uid: user.uid ?? "")
+    .hideDeletedMessages(hide: true)
+    .set(limit: 30)
+)
+```
+
+### Filter Users
+
+```swift
+let users = CometChatUsers()
+
+// Only show users with specific role
+users.set(usersRequestBuilder: UsersRequest.UsersRequestBuilder()
+    .set(roles: ["admin", "moderator"])
+    .set(limit: 30)
+)
+
+// Only show friends
+users.set(usersRequestBuilder: UsersRequest.UsersRequestBuilder()
+    .friendsOnly(true)
+    .set(limit: 30)
+)
+
+// Search users
+users.set(usersRequestBuilder: UsersRequest.UsersRequestBuilder()
+    .set(searchKeyword: "john")
+    .set(limit: 30)
+)
+```
+
+### Filter Groups
+
+```swift
+let groups = CometChatGroups()
+
+// Only show joined groups
+groups.set(groupsRequestBuilder: GroupsRequest.GroupsRequestBuilder()
+    .set(joinedOnly: true)
+    .set(limit: 30)
+)
+
+// Only show public groups
+groups.set(groupsRequestBuilder: GroupsRequest.GroupsRequestBuilder()
+    .set(groupType: .public)
+    .set(limit: 30)
+)
+
+// Search groups
+groups.set(groupsRequestBuilder: GroupsRequest.GroupsRequestBuilder()
+    .set(searchKeyWord: "team")
+    .set(limit: 30)
+)
+```
+
+---
+
+## 7. DataSource Decorator Pattern
+
+For advanced customization, use the DataSource decorator pattern:
+
+```swift
+class CustomDataSource: DataSourceDecorator {
+    
+    override func getAllMessageTemplates() -> [CometChatMessageTemplate] {
+        var templates = super.getAllMessageTemplates()
+        
+        // Add custom template
+        let customTemplate = CometChatMessageTemplate(type: "custom_type", category: "custom")
+        templates.append(customTemplate)
+        
+        return templates
+    }
+    
+    override func getAllMessageTypes() -> [String]? {
+        var types = super.getAllMessageTypes() ?? []
+        types.append("custom_type")
+        return types
+    }
+    
+    override func getAllMessageCategories() -> [String]? {
+        var categories = super.getAllMessageCategories() ?? []
+        categories.append("custom")
+        return categories
+    }
+    
+    override func getMessageOptions(
+        loggedInUser: User,
+        messageObject: BaseMessage,
+        controller: UIViewController?,
+        group: Group?
+    ) -> [CometChatMessageOption]? {
+        var options = super.getMessageOptions(
+            loggedInUser: loggedInUser,
+            messageObject: messageObject,
+            controller: controller,
+            group: group
+        ) ?? []
+        
+        // Add custom option
+        let customOption = CometChatMessageOption(
+            id: "custom_action",
+            title: "Custom Action",
+            icon: UIImage(systemName: "star.fill")
+        )
+        customOption.onClick = { _, _, _, _ in
+            print("Custom action triggered")
+        }
+        options.append(customOption)
+        
+        return options
+    }
+}
+
+// Register custom data source
+ChatConfigurator.enable { dataSource in
+    return CustomDataSource(dataSource: dataSource)
+}
+```
+
+---
+
+## Best Practices
+
+1. **Keep custom views lightweight** — Complex views affect scroll performance
+2. **Reuse views when possible** — Use cell reuse patterns
+3. **Handle all message types** — Don't forget edge cases
+4. **Test with real data** — Use actual conversations for testing
+5. **Clean up listeners** — Remove event listeners when views are deallocated
+6. **Use weak references** — Avoid retain cycles in closures