@cometchat/skills 4.2.1 → 4.4.0

package/skills/cometchat-components/SKILL.md

@@ -3,19 +3,36 @@ name: cometchat-components
 description: "Complete catalog of CometChat React UI Kit v6 components. Reference before writing integration code -- never invent component names."
 license: "MIT"
 compatibility: "@cometchat/chat-uikit-react ^6; @cometchat/chat-sdk-javascript ^4"
-allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "chat cometchat react components catalog reference ui-kit"
 ---
 
+> **Ground truth:** `@cometchat/chat-uikit-react@^6` component catalog (installed package types) + `docs/ui-kit/react`. **Official docs:** https://www.cometchat.com/docs/ui-kit/react/components-overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.
+
 ## Purpose
 
 This is the single source of truth for CometChat React UI Kit v6 component names, props, and usage. **Check this catalog before writing any `<CometChat*>` JSX.** If a component is not listed here, it does not exist in the exported API.
 
 All components are imported from `@cometchat/chat-uikit-react`. All SDK types are imported from `@cometchat/chat-sdk-javascript`.
 
+## When to use
+
+- Any React-family integration emitting `<CometChat*>` JSX: Vite + React, Next.js (App or Pages Router), React Router v6/v7, Astro with React islands.
+- Before scaffolding any chat surface (conversations, messages, users, groups, calls UI).
+- When verifying a component name or prop signature — this catalog is authoritative; the kit's `node_modules/@cometchat/chat-uikit-react/dist/types/` is the runtime source of truth that backs it.
+
+## When NOT to use
+
+- **React Native** (Expo or bare) — load `cometchat-native-components`. Class names are similar but **prop conventions diverge** (RN uses `onItemPress`, web uses `onItemClick` — runtime smoke 2026-06-02 confirmed). Cross-family copy-paste produces silent broken event bindings.
+- **Angular** — load `cometchat-angular-components`. Angular kit class names are **`Component`-suffixed** (`CometChatConversationsComponent` not `CometChatConversations` — verified by runtime smoke 2026-06-02), HTML selectors are kebab-case, event bindings use round brackets for `@Output()` events. Different shape entirely.
+- **Native Android** — load `cometchat-android-v6-{compose,kotlin}-components` (V6) or `cometchat-android-v5-components` (V5). Different package namespaces (`com.cometchat.uikit.compose.*` vs `com.cometchat.chatuikit.*`) — never reuse React component names.
+- **iOS V5** — load `cometchat-ios-components`. UIKit Swift surface; `CometChatConversations()` zero-arg initializer + `.set(group: ...)` pattern; nothing like the React prop API.
+- **Flutter V5 / V6** — load `cometchat-flutter-{v5,v6}-components`. Dart widget API with named parameters; V5 GetX vs V6 Bloc state-management split changes lifecycle.
+- **Theming-only tasks** — load `cometchat-theming` (CSS variables, recipes) for color/font customization without component changes.
+- **SDK-only chat (no UI Kit)** — this catalog assumes UI Kit components. If a future skill ships for the pure-SDK path (no `<CometChat*>` JSX), defer to it; today the closest analog is the SDK-only patterns inside `cometchat-react-calls` §4c.
+
 ### Importing `CometChat.User` / `CometChat.Group` / etc.
 
 `CometChat.User`, `CometChat.Group`, `CometChat.BaseMessage`, `CometChat.Conversation`, `CometChat.GroupMember`, `CometChat.TextMessage` are **classes** (runtime values), not pure types. That means the import strategy depends on how you use them:
@@ -50,6 +67,35 @@ function renderHeader(user: CometChat.User) { ... }
 
 ## 1. Core messaging
 
+> ⛔ **STOP — only the components in THIS catalog exist. Do not invent or recall component names from v4/older memory.** Before emitting ANY `CometChat*` component, confirm it appears in this catalog (or the kit's exports). If it's not here, it does not exist — using it produces an **unresolved-import build failure** or a blank screen. This is the #1 failure class on this skill.
+>
+> **The real v6 component set (the ONLY ones — `import { … } from "@cometchat/chat-uikit-react"`):** `CometChatConversations`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer` (+ `CometChatCompactMessageComposer`), `CometChatUsers`, `CometChatGroups`, `CometChatMessageInformation` (+ the calling/feature components in their own catalogs).
+>
+> **Commonly hallucinated names that were REMOVED in v6 (verified absent from the kit exports) — do NOT use:** the all-in-one composites `CometChatConversationsWithMessages`, `CometChatUsersWithMessages`, `CometChatGroupsWithMessages`, the `CometChatMessages` composite, and the `CometChatUI` god-component. **There is no single "conversations + messages" component in v6** — you compose the two panes yourself (recipe below). (Note: `CometChatMessages`/`CometChatConversationsWithMessages` DO still exist in the Flutter v6 kit — this removal is web/RN/Angular. Always check the per-family catalog.)
+
+> **The canonical two-pane experience (what "CometChatConversationsWithMessages" used to do — now hand-composed):**
+> ```tsx
+> const [active, setActive] = useState<CometChat.Conversation | null>(null);
+> // pick the peer the message views need from the selected conversation:
+> const peer = active?.getConversationWith(); // CometChat.User | CometChat.Group
+> return (
+>   <div style={{ display: "flex", height: "100%" }}>
+>     <div style={{ width: 320 }}>
+>       <CometChatConversations activeConversation={active ?? undefined}
+>         onItemClick={(c) => setActive(c)} />
+>     </div>
+>     <div style={{ flex: 1, display: "flex", flexDirection: "column" }}>
+>       {peer && <>
+>         <CometChatMessageHeader {...(peer instanceof CometChat.User ? { user: peer } : { group: peer })} />
+>         <CometChatMessageList   {...(peer instanceof CometChat.User ? { user: peer } : { group: peer })} />
+>         <CometChatMessageComposer {...(peer instanceof CometChat.User ? { user: peer } : { group: peer })} />
+>       </>}
+>     </div>
+>   </div>
+> );
+> ```
+> A `CometChatMessageHeader`/`List`/`Composer` takes EITHER `user=` OR `group=` (never both) — derive it from the clicked conversation. Conversations-list-only and single-conversation-only are both valid subsets of this.
+
 These are the components you use to build a chat experience. Most integrations use some combination of these seven.
 
 ### CometChatConversations
@@ -172,6 +218,20 @@ Displays the name, avatar, and status of the user or group at the top of a messa
 
 **Works with:** CometChatMessageList (below), CometChatCallButtons (in auxiliaryButtonView slot)
 
+> ⚠️ **Header `onItemClick` has NO default behavior (ENG-35705).** The kit ships no built-in `<CometChatUserDetails />` / `<CometChatGroupDetails />` panel — clicking the header name/avatar produces zero visible feedback unless YOU pass an `onItemClick` callback. **Four testers flagged this as "kit feels broken."** Rule when emitting `<CometChatMessageHeader>`:
+> 1. Either provide an `onItemClick` that opens a details panel YOU built (use the sample-app reference at `sample-app/src/components/CometChatDetails/`), OR
+> 2. Wrap the header in a clickable region that goes elsewhere, so the avatar+name doesn't *look* like a dead end. (There is no `showInfo` prop on `CometChatMessageHeader` — don't emit it.)
+> Do NOT mount the header bare without an `onItemClick` — it's a customer-facing dead end.
+
+> ⚠️ **`Reply in Thread` action requires the host to wire the thread panel (ENG-35705 — clarified 2026-06-02 from "broken" to "requires wiring").** The kit's `<CometChatMessageList>` renders a "Reply in Thread" item in the message-options menu and fires `onThreadRepliesClick(parentMessage)` when tapped — but the kit does NOT ship a default thread screen. If the host doesn't bind `onThreadRepliesClick` to a thread surface, the action visually does nothing (callback fires; no UI follows). Two paths:
+>
+> 1. **You're not building threads** — set `hideReplyInThreadOption={true}` on `<CometChatMessageList>` to remove the menu item entirely.
+> 2. **You ARE building threads** — bind `onThreadRepliesClick={(parent) => /* open thread surface */}` and render a separate `<CometChatMessageList parentMessageId={parent.getId()} />` inside the thread surface. Sample app's pattern: `cometchat-uikit-react-v6/sample-app/src/components/CometChatMessages/CometChatMessages.tsx:74` wires this via parent component routing.
+>
+> The dispatcher hard rule still defaults to option 1 (hide threads) because most integrations don't want them. Restated here at point-of-use so the catalog reader makes a conscious choice.
+
+> ⚠️ **`Message Privately` action — hide it via the kit prop if it misbehaves (ENG-35705).** In group chats the message-options menu shows a "Message Privately" item that may do nothing on click in some kit versions. `<CometChatMessageList>` exposes `hideMessagePrivatelyOption={true}` to remove it cleanly — set that rather than living with a dead menu item.
+
 ---
 
 ### CometChatSearch
@@ -295,12 +355,13 @@ A standalone search input component. Used for filtering within other components.
 **Key props:**
 | Prop | Type | Description |
 |---|---|---|
-| `onSearch` | `(text: string) => void` | Called as the user types |
-| `text` | `string` | Controlled input value |
+| `onChange` | `(input: { value?: string }) => void` | Called as the user types — read `input.value` |
+| `searchText` | `string` | Controlled input value |
+| `placeholderText` | `string` | Placeholder text |
 
 **Usage:**
 ```tsx
-<CometChatSearchBar onSearch={(text) => filterUsers(text)} />
+<CometChatSearchBar onChange={(input) => filterUsers(input.value ?? "")} />
 ```
 
 **Works with:** Any list component for client-side filtering
@@ -328,7 +389,7 @@ Renders voice and video call buttons. Typically placed in the `auxiliaryButtonVi
 <CometChatCallButtons user={selectedUser} />
 ```
 
-**Works with:** CometChatMessageHeader (in `menu` prop), CometChatIncomingCall (at app root)
+**Works with:** CometChatMessageHeader (via its `auxiliaryButtonView` prop — there is no `menu` prop), CometChatIncomingCall (at app root)
 
 ---
 
@@ -413,6 +474,60 @@ Shows a detailed list of who reacted with what emoji on a specific message.
 
 ---
 
+## 5. Notifications (catalog gap closed 2026-06-02)
+
+Three notification-related exports that were missing from this catalog before today. Verified against `cometchat-uikit-react-v6/src/index.ts:167-169`.
+
+### CometChatNotificationFeed
+
+A scrollable inbox of campaign / promotional notifications. Renders a list view; integrators wire it as a dropdown or dedicated route.
+
+**Key props:** `onItemClick: (feedItem: NotificationFeedItem) => void` to handle taps; `notificationFeedRequestBuilder` (and `notificationCategoriesRequestBuilder`) to filter — NOT `notificationsRequestBuilder`.
+
+**Usage:**
+```tsx
+import { CometChatNotificationFeed } from "@cometchat/chat-uikit-react";
+
+// feedItem is a NotificationFeedItem (campaign notification) — it has no
+// `conversationId`; route off its own fields / deep-link payload.
+<CometChatNotificationFeed onItemClick={(feedItem) => handleNotification(feedItem)} />
+```
+
+---
+
+### CometChatNotificationBadge
+
+A small unread-count pill, designed to attach to a nav item / icon. Auto-updates as new notifications arrive via the kit's notification feed listener.
+
+**Key props:** All optional — defaults to showing the current unread count of the logged-in user. Style with the standard `CometChat*Style` pattern.
+
+**Usage:**
+```tsx
+import { CometChatNotificationBadge } from "@cometchat/chat-uikit-react";
+
+<button onClick={openNotificationFeed}>
+  <BellIcon />
+  <CometChatNotificationBadge />
+</button>
+```
+
+---
+
+### useNotificationUnreadCount (hook)
+
+React hook returning the current unread-notification count for the logged-in user. Use this when `<CometChatNotificationBadge />` doesn't fit your layout — gives you the raw number to render however you like.
+
+**Signature:**
+```tsx
+import { useNotificationUnreadCount } from "@cometchat/chat-uikit-react";
+
+const { count, isLoading } = useNotificationUnreadCount({ /* optional UseNotificationUnreadCountOptions */ });
+```
+
+Internally subscribes to the same notification stream as `CometChatNotificationBadge` — using both is safe (single shared source).
+
+---
+
 ### CometChatEmojiKeyboard
 
 A full emoji picker. Automatically rendered inside the message composer when the emoji button is clicked.
@@ -439,9 +554,9 @@ An AI chatbot interface that users can interact with for automated responses. Ty
 
 **Prerequisites:** Enable "Conversation Starter" and/or "Smart Replies" in the dashboard.
 
-**Usage:**
+**Usage:** `user` is a **required** prop (the AI assistant user to chat with):
 ```tsx
-<CometChatAIAssistantChat />
+<CometChatAIAssistantChat user={assistantUser} />
 ```
 
 ---
@@ -459,13 +574,14 @@ Displays past AI assistant interactions. Used alongside `CometChatAIAssistantCha
 
 ### CometChatAIAssistantTools
 
-Renders AI tool options (summarize conversation, translate message, etc.) that can be applied to messages or conversations.
+⚠️ **This is a CLASS, not a renderable component.** You instantiate it with a map of action functions and pass it to `<CometChatAIAssistantChat>` via the `aiAssistantTools` prop — do NOT render `<CometChatAIAssistantTools />` (it's a type error).
 
 **Prerequisites:** Enable "Conversation Summary" and/or other AI tools in the dashboard.
 
 **Usage:**
 ```tsx
-<CometChatAIAssistantTools />
+const toolkit = new CometChatAIAssistantTools({ /* actionsMap */ });
+<CometChatAIAssistantChat user={assistantUser} aiAssistantTools={toolkit} />
 ```
 
 > **Note:** For detailed props, configuration options, and customization of AI components, query the docs MCP — these components' APIs evolve with CometChat's AI feature releases.
@@ -615,10 +731,15 @@ import {
   CometChatConversations,
   CometChatMessageHeader,
   CometChatMessageList,
-  CometChatMessageComposer,
+  CometChatCompactMessageComposer,
 } from "@cometchat/chat-uikit-react";
 import { CometChat } from "@cometchat/chat-sdk-javascript";
 
+// The message list must scroll inside a flex column without pushing the
+// composer off-screen. Mirror the sample app's list wrapper.
+// .cc-msg-list { flex: 1 1 0; min-height: 0; overflow: hidden; }
+// .cc-msg-list > .cometchat { height: 100%; overflow: hidden; }
+
 function MultiConversation() {
   const [activeConversation, setActiveConversation] = useState<CometChat.Conversation>();
 
@@ -639,15 +760,19 @@ function MultiConversation() {
         {selectedUser && (
           <>
             <CometChatMessageHeader user={selectedUser} />
-            <CometChatMessageList user={selectedUser} />
-            <CometChatMessageComposer user={selectedUser} />
+            <div className="cc-msg-list">
+              <CometChatMessageList user={selectedUser} />
+            </div>
+            <CometChatCompactMessageComposer user={selectedUser} />
           </>
         )}
         {selectedGroup && (
           <>
             <CometChatMessageHeader group={selectedGroup} />
-            <CometChatMessageList group={selectedGroup} />
-            <CometChatMessageComposer group={selectedGroup} />
+            <div className="cc-msg-list">
+              <CometChatMessageList group={selectedGroup} />
+            </div>
+            <CometChatCompactMessageComposer group={selectedGroup} />
           </>
         )}
       </div>
@@ -666,7 +791,7 @@ One chat window for a known user or group. No conversation list.
 import {
   CometChatMessageHeader,
   CometChatMessageList,
-  CometChatMessageComposer,
+  CometChatCompactMessageComposer,
 } from "@cometchat/chat-uikit-react";
 import { CometChat } from "@cometchat/chat-sdk-javascript";
 
@@ -675,15 +800,20 @@ interface SingleThreadProps {
   group?: CometChat.Group;
 }
 
+// .cc-msg-list { flex: 1 1 0; min-height: 0; overflow: hidden; }
+// .cc-msg-list > .cometchat { height: 100%; overflow: hidden; }
+
 function SingleThread({ user, group }: SingleThreadProps) {
   return (
     <div style={{ display: "flex", flexDirection: "column", height: "100%" }}>
       {user && <CometChatMessageHeader user={user} />}
       {group && <CometChatMessageHeader group={group} />}
-      {user && <CometChatMessageList user={user} />}
-      {group && <CometChatMessageList group={group} />}
-      {user && <CometChatMessageComposer user={user} />}
-      {group && <CometChatMessageComposer group={group} />}
+      <div className="cc-msg-list">
+        {user && <CometChatMessageList user={user} />}
+        {group && <CometChatMessageList group={group} />}
+      </div>
+      {user && <CometChatCompactMessageComposer user={user} />}
+      {group && <CometChatCompactMessageComposer group={group} />}
     </div>
   );
 }
@@ -717,10 +847,13 @@ import {
   CometChatGroups,
   CometChatMessageHeader,
   CometChatMessageList,
-  CometChatMessageComposer,
+  CometChatCompactMessageComposer,
 } from "@cometchat/chat-uikit-react";
 import { CometChat } from "@cometchat/chat-sdk-javascript";
 
+// .cc-msg-list { flex: 1 1 0; min-height: 0; overflow: hidden; }
+// .cc-msg-list > .cometchat { height: 100%; overflow: hidden; }
+
 type Tab = "chats" | "calls" | "users" | "groups";
 
 function FullMessenger() {
@@ -794,15 +927,19 @@ function FullMessenger() {
         {selectedUser && (
           <>
             <CometChatMessageHeader user={selectedUser} />
-            <CometChatMessageList user={selectedUser} />
-            <CometChatMessageComposer user={selectedUser} />
+            <div className="cc-msg-list">
+              <CometChatMessageList user={selectedUser} />
+            </div>
+            <CometChatCompactMessageComposer user={selectedUser} />
           </>
         )}
         {selectedGroup && (
           <>
             <CometChatMessageHeader group={selectedGroup} />
-            <CometChatMessageList group={selectedGroup} />
-            <CometChatMessageComposer group={selectedGroup} />
+            <div className="cc-msg-list">
+              <CometChatMessageList group={selectedGroup} />
+            </div>
+            <CometChatCompactMessageComposer group={selectedGroup} />
           </>
         )}
       </div>
@@ -968,7 +1105,8 @@ User and group detail panels are **custom-built** — there is no pre-built `Com
         // Switch to 1:1 chat with this member
       }}
     />
-    {/* CometChatBannedMembers is a real kit component */}
+    {/* Banning is handled inside CometChatGroupMembers — there is no separate
+        CometChatBannedMembers export in the v6 kit. */}
   </div>
 )}
 ```