@tencent-rtc/mcp 1.3.8 → 1.4.0

package/resource/doc/{chatuikit → chatkit}/vue/components/component-list.md

@@ -1,15 +1,11 @@
 # atomicx component library Manifest and components Application scenarios and considerations
 
-
 ## Component list
 
-
 25 components:
 
-
 ### Components suitable for chat scenarios
 
-
 1. ConversationList
   Session list component, suitable for chat scenarios, in vertical list form, can switch sessions through click. If only chat is needed, this component is optional.
 2. MessageInput
@@ -23,10 +19,8 @@
 6. Search
   Search component, used for message search, user search, etc. If only chat is needed, this component is optional.
 
-
 ### Components suitable for meeting scenarios
 
-
 1. CameraButton
   Camera control button, applicable only to meeting scenarios, used to turn the camera on/off
 2. StreamView
@@ -50,12 +44,8 @@
 11. MicButton
   Microphone control button, suitable for meeting and live-streaming scenarios, used for mute/unmute.
 
-
-
-
 ### Components for live streaming scenarios
 
-
 1. CoGuestPanel
   Co-anchoring guest management panel, only applicable to live broadcast scenarios, used for the co-anchoring function.
 2. LiveAudienceList
@@ -79,22 +69,17 @@
 11. MicButton
   Microphone control button, suitable for meeting and live-streaming scenarios, used for mute/unmute.
 
-
 ### universal component
 
-
 1. Avatar
   Common avatar component, displays user profile photo, online status, and message unread count.
 2. UserPicker
   User selector, used to initiate group chat, group video, or group voice calls in user selection scenarios.
 
-
 ## Must-Knows
 
-
 Before integrating any component into a real project, **must** first ensure the integration documentation has been obtained using the following tool and integrate according to the documentation:
 
-
 1. When creating a real project, call the component integration documentation of MCP Tools get_atomicx_integration_guide(framework).
 2. When choosing to use components, first consider the minimum components that meet the requirements, then consider recommended additional extension components. Do not enlarge the requirements.
 3. Components that apply to different scenarios may have an intersection.

package/resource/doc/chatkit/vue/components/contact-list.md

@@ -0,0 +1,271 @@
+## Overview
+
+ContactList is a highly configurable contact list component. This component supports friend lists, group lists, blacklists, and application management, providing core features such as group collapsing, search filtering, and custom rendering. It's suitable for contact management interfaces in instant messaging and social applications.
+
+## ContactList Props
+| Field | Type | Default Value | Description |
+| --- | --- | --- | --- |
+| activeContactItem | ContactGroupItem \\| undefined | undefined | Currently active contact item |
+| enableSearch | boolean | true | Whether to enable search functionality |
+| groupConfig | Partial<Record<ContactItemType, CustomGroupConfig>> | {} | Custom group configuration |
+| searchPlaceholder | string | 'Search contacts' | Search box placeholder text |
+| emptyText | string | 'No contacts' | Empty state message text |
+| ContactItem | Component \\| undefined | ContactListItem | Custom contact item component |
+| ContactSearchComponent | Component \\| undefined | ContactSearch | Custom search component |
+| GroupHeader | Component \\| undefined | Default group header | Custom group header component |
+| PlaceholderEmptyList | Component \\| undefined | Default empty state | Custom empty state component |
+| onContactItemClick | (item: ContactGroupItem) => void | undefined | Contact item click event |
+| onFriendApplicationAction | (action: 'accept' \\| 'refuse', application: FriendApplication) => void | undefined | Friend application action event |
+| onGroupApplicationAction | (action: 'accept' \\| 'refuse', application: GroupApplication) => void | undefined | Group application action event |
+
+## ContactList Events
+| Event Name | Parameters | Description |
+| --- | --- | --- |
+| contact-item-click | (item: ContactGroupItem) | Contact item click event |
+| friend-application-action | (action: 'accept' \\| 'refuse', application: FriendApplication) | Friend application action event |
+| group-application-action | (action: 'accept' \\| 'refuse', application: GroupApplication) | Group application action event |
+
+## ContactInfo Props
+| Field | Type | Default Value | Description |
+| --- | --- | --- | --- |
+| contactItem | ContactGroupItem \\| undefined | undefined | Currently displayed contact item |
+| showActions | boolean | true | Whether to show action buttons |
+| PlaceholderEmpty | Component \\| undefined | undefined | Empty state placeholder component |
+| FriendInfoComponent | Component | FriendInfo | Friend info component |
+| GroupInfoComponent | Component | GroupInfo | Group info component |
+| BlacklistInfoComponent | Component | BlacklistInfo | Blacklist info component |
+| FriendApplicationInfoComponent | Component | FriendApplicationInfo | Friend application info component |
+| GroupApplicationInfoComponent | Component | GroupApplicationInfo | Group application info component |
+| SearchGroupInfoComponent | Component | SearchGroupInfo | Search group info component |
+| SearchUserInfoComponent | Component | SearchUserInfo | Search user info component |
+
+## ContactInfo Events
+| Event Name | Parameters | Description |
+| --- | --- | --- |
+| close | - | Close info panel event |
+| sendMessage | (friend: Friend) | Send message event |
+| deleteFriend | (friend: Friend) | Delete friend event |
+| addToBlacklist | (friend: Friend) | Add to blacklist event |
+| removeFromBlacklist | (profile: UserProfile) | Remove from blacklist event |
+| updateFriendRemark | (friend: Friend) | Update friend remark event |
+| enterGroup | (group: GroupModel) | Enter group event |
+| leaveGroup | (group: GroupModel) | Leave group event |
+| dismissGroup | (group: GroupModel) | Dismiss group event |
+| friendApplicationAction | (action: 'accept' \\| 'refuse', application: FriendApplication) | Friend application action event |
+| groupApplicationAction | (action: 'accept' \\| 'refuse', application: GroupApplication) | Group application action event |
+| addFriend | (user: UserProfile, wording: string) | Add friend event |
+| joinGroup | (group: GroupModel, note: string) | Join group event |
+
+## Basic Usage
+``` typescript
+<template>
+  <div class="contact-container">
+    <ContactList />
+    <ContactInfo />
+  </div>
+</template>
+
+<script setup lang="ts">
+import { ContactList, ContactInfo } from '@tencentcloud/chat-uikit-vue3';
+</script>
+
+<style scoped>
+.contact-container {
+  display: flex;
+  height: 100vh;
+}
+</style>
+```
+
+## Customization
+
+### Customize Contact List Search Toggle
+
+By setting the `enableSearch` parameter, you can flexibly control the display of the friend/group search functionality in ContactList.
+``` typescript
+<template>
+  <ContactList :enableSearch="false" />
+</template>
+```
+| enableSearch="true" | enableSearch="false" |
+| --- | --- |
+|  |  |
+
+### Customize Contact List Group Configuration
+
+`groupConfig` is used to customize group configuration, including title, display order, hiding groups, etc.
+``` typescript
+<template>
+  <ContactList :groupConfig="customGroupConfig" />
+</template>
+
+<script setup lang="ts">
+import { ContactList } from '@tencentcloud/chat-uikit-vue3';
+import { ContactItemType } from '@tencentcloud/chat-uikit-vue3';
+
+const customGroupConfig = {
+  [ContactItemType.FRIEND]: {
+    title: 'My Friends',
+    order: 1,
+  },
+  [ContactItemType.GROUP]: {
+    title: 'Group Chats',
+    order: 2,
+  },
+  [ContactItemType.BLACK]: {
+    hidden: true,
+  },
+  [ContactItemType.FRIEND_REQUEST]: {
+    title: 'Friend Requests',
+    order: 0,
+  }
+};
+</script>
+```
+| Before | After |
+| --- | --- |
+|  |  |
+
+### Customize Contact List Items
+
+You can fully control the rendering of contact list items by passing in a custom `ContactItem` component.
+``` typescript
+<template>
+  <div class="custom-contact-item" @click="handleClick">
+    <label>Custom Contact</label>
+    <span v-if="props.contactItem.type === ContactItemType.FRIEND">{{ props.contactItem.data.nick }}</span>
+    <span v-if="props.contactItem.type === ContactItemType.GROUP">{{ props.contactItem.data.name }}</span>
+  </div>
+</template>
+<script setup lang="ts">
+import { ContactItemType } from '@tencentcloud/chat-uikit-vue3';
+
+const props = defineProps<{
+  contactItem: any;
+}>();
+const emit = defineEmits<{
+  click: [type: ContactItemType, item: any];
+}>();
+const handleClick = () => {
+  emit('click', props.contactItem.type, props.contactItem.data);
+};
+</script>
+<style scoped>
+.custom-contact-item {
+  display: flex;
+  align-items: center;
+  gap: 10px;
+  padding: 10px 20px;
+  border-bottom: 1px solid #eee;
+}
+</style>
+
+```
+``` typescript
+<template>
+  <ContactList :ContactItem="CustomContactItem" />
+</template>
+
+<script setup lang="ts">
+import { ContactList } from '@tencentcloud/chat-uikit-vue3';
+import CustomContactItem from './CustomContactItem.vue';
+</script>
+```
+| Before | After |
+| --- | --- |
+|  |  |
+
+### Customize Contact Details Action Button Toggle
+
+By setting the `showActions` parameter, you can control the display of action buttons on the contact details page.
+``` typescript
+<template>
+  <ContactInfo
+    :showActions="false"
+  />
+</template>
+```
+| Before | After |
+| --- | --- |
+|  |  |
+
+### Customize Contact Details Empty State
+
+When no contact is selected, you can customize the empty state component to display.
+``` typescript
+<template>
+  <div>
+    Custom Empty State
+  </div>
+</template>
+```
+``` typescript
+<template>
+  <ContactInfo
+    :PlaceholderEmpty="CustomEmpty"
+  />
+</template>
+
+<script setup lang="ts">
+import { ContactList } from '@tencentcloud/chat-uikit-vue3';
+import CustomEmpty from './CustomEmpty.vue';
+</script>
+```
+
+### Customize Friend Details Component
+
+You can customize the detail display component for different types of contacts.
+``` typescript
+<template>
+  <div class="custom-contact-info">
+    <label>Custom Friend Details</label>
+    <div class="friend-info">
+
+      <span>{{ friend.nick }}</span>
+    </div>
+  </div>
+</template>
+<script setup lang="ts">
+import type { Friend } from '@tencentcloud/chat-uikit-vue3';
+
+defineProps<{
+  friend: Friend;
+}>();
+</script>
+<style scoped>
+.custom-contact-info {
+  display: flex;
+  flex-direction: column;
+  gap: 10px;
+  padding: 20px;
+}
+.friend-info {
+  display: flex;
+  justify-content: space-between;
+  align-items: center;
+  gap: 10px;
+}
+.avatar {
+  width: 60px;
+  height: 60px;
+  border-radius: 50%
+}
+</style>
+
+```
+``` typescript
+<template>
+  <ContactInfo
+    :FriendInfoComponent="CustomFriendInfo"
+  />
+</template>
+
+<script setup lang="ts">
+import { defineComponent, h } from 'vue';
+import type { FriendInfoProps, GroupInfoProps } from '@tencentcloud/chat-uikit-vue3';
+import CustomFriendInfo from './CustomFriendInfo.vue';
+</script>
+```
+| Before | After |
+| --- | --- |
+|  |  |

package/resource/doc/chatkit/vue/components/conversation-actions.md

@@ -0,0 +1,228 @@
+## Overview
+
+The ConversationActions component handles operations for a single conversation, supporting delete, pin, mute, and mark unread/read by default.
+
+## Basic Usage
+
+In `ConversationList`, you can quickly customize conversation actions using the `actionsConfig` prop.
+``` typescript
+<template>
+  <UIKitProvider>
+    <ConversationList :actions-config="actionsConfig" />
+  </UIKitProvider>
+</template>
+
+<script setup lang="ts">
+import { UIKitProvider, ConversationList } from '@tencentcloud/chat-uikit-vue3';
+import type { ConversationModel } from '@tencentcloud/chat-uikit-vue3';
+
+const actionsConfig = {
+  enablePin: false,
+  onConversationDelete: (conversation: ConversationModel) => {
+    console.log('Delete conversation success');
+  },
+  customConversationActions: {
+    'custom-actions-1': {
+      label: 'custom-actions',
+      onClick: (conversation: ConversationModel) => {
+        console.log(conversation);
+      },
+    },
+  },
+};
+</script>
+```
+
+## Advanced Usage
+
+For deeper customization, you can directly replace the `ConversationActions` prop of `ConversationList`.
+``` typescript
+<template>
+  <UIKitProvider>
+    <ConversationList
+      :ConversationActions="CustomConversationActions"
+    />
+  </UIKitProvider>
+</template>
+
+<script setup lang="ts">
+import { defineComponent } from 'vue';
+import { UIKitProvider, ConversationList, ConversationActions } from '@tencentcloud/chat-uikit-vue3';
+import type { ConversationActionsProps } from '@tencentcloud/chat-uikit-vue3';
+
+const CustomConversationActions = defineComponent({
+  name: 'CustomConversationActions',
+  setup(props: ConversationActionsProps) {
+    return () => h(ConversationActions, {
+      ...props,
+      enableDelete: false
+    });
+  }
+});
+</script>
+```
+
+## Props
+
+The `ConversationActionsProps` interface type for the ConversationActions component extends from the `ConversationActionsConfig` interface.
+
+### ConversationActionsProps
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| conversation(Required) | ConversationModel | - | Required parameter, represents the conversation for the current rendered conversation action |
+| className | string | - | Custom class name for root element |
+| style | CSSProperties | - | Custom style for root element |
+
+### ConversationActionsConfig
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| enablePin | boolean | true | Whether to show the pin action button |
+| enableMute | boolean | true | Whether to show the mute action button |
+| enableDelete | boolean | true | Whether to show the delete action button |
+| enableMarkUnread | boolean | true | Whether to show the mark unread action button |
+| onMarkConversationUnread | (conversation: ConversationModel, e?: Event) => void | - | Custom callback for marking conversation as unread/read |
+| onConversationPin | (conversation: ConversationModel, e?: Event) => void | - | Custom callback for pinning/unpinning conversation |
+| onConversationMute | (conversation: ConversationModel, e?: Event) => void | - | Custom callback for muting/unmuting conversation |
+| onConversationDelete | (conversation: ConversationModel, e?: Event) => void | - | Custom callback for deleting conversation |
+| customConversationActions | Record<string, ConversationActionItem> | - | Custom conversation action items |
+| PopupIcon | any | - | Custom icon for action popup |
+| PopupElements | any[] | - | Custom content for action popup |
+| onClick | (e: Event, key?: string, conversation?: ConversationModel) => void | - | Callback when clicking action item |
+| onClose | () => void | - | Callback when closing action popup (H5 only) |
+
+### ConversationActionItem
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| enable | boolean | true | Whether to enable the custom action item |
+| label | string | - | Display content for custom action item |
+| onClick | (conversation: ConversationModel, e?: Event) => void | - | Callback when clicking custom action item |
+
+## Events
+| Event Name | Parameters | Description |
+| --- | --- | --- |
+| click | (e: Event, key?: string, conversation?: ConversationModel) | Triggered when clicking an action item |
+| close | () | Triggered when closing the action popup |
+| markConversationUnread | (conversation: ConversationModel, e?: Event) | Triggered when marking conversation as unread/read |
+| conversationPin | (conversation: ConversationModel, e?: Event) | Triggered when pinning/unpinning conversation |
+| conversationMute | (conversation: ConversationModel, e?: Event) | Triggered when muting/unmuting conversation |
+| conversationDelete | (conversation: ConversationModel, e?: Event) | Triggered when deleting conversation |
+
+## Custom Components
+
+### Basic Feature Toggles
+
+By setting `enablePin`, `enableDelete`, `enableMute`, and `enableMarkUnread` parameters, you can flexibly control the display of conversation pin, mute, delete, and mark unread in `ConversationActions`.
+``` typescript
+<template>
+  <!-- Disable pin feature -->
+  <ConversationActions :enablePin="false" :conversation="conversation" />
+
+  <!-- Disable delete feature -->
+  <ConversationActions :enableDelete="false" :conversation="conversation" />
+
+  <!-- Disable mute feature -->
+  <ConversationActions :enableMute="false" :conversation="conversation" />
+
+  <!-- Disable mark unread feature -->
+  <ConversationActions :enableMarkUnread="false" :conversation="conversation" />
+</template>
+```
+| `enablePin: false` | `enableDelete: false` | `enableMute: false` | enableMarkUnread="false" |
+| --- | --- | --- | --- |
+|  |  |  |  |
+
+### Event Handling
+
+The ConversationActions component supports conversation delete, pin/unpin, mute/unmute, and mark unread/read by default. If the existing event handling doesn't meet your needs, you can customize and override the event handling functions. In addition to customizing event handling, you can also get basic click events through `@click`.
+``` typescript
+<template>
+  <ConversationList :conversation-actions="CustomConversationActions" />
+</template>
+
+<script setup lang="ts">
+import { defineComponent, h } from 'vue';
+import { ConversationActions, Toast } from '@tencentcloud/chat-uikit-vue3';
+import type { ConversationActionsProps, ConversationModel } from '@tencentcloud/chat-uikit-vue3';
+
+const CustomConversationActions = defineComponent({
+  name: 'CustomConversationActions',
+  setup(props: ConversationActionsProps) {
+    const handleConversationDelete = (conversation: ConversationModel) => {
+      conversation.deleteConversation().then(() => {
+        console.log('delete conversation successfully!');
+      }).catch(() => {
+        console.log('delete conversation failed!');
+      });
+    };
+
+    return () => h(ConversationActions, {
+      ...props,
+      onConversationDelete: handleConversationDelete
+    });
+  }
+});
+</script>
+```
+
+### Custom Actions
+
+customConversationActions is used to add custom action items to ConversationActions.
+
+**Example: Add Custom Action Item**
+``` typescript
+<template>
+  <ConversationList :ConversationActions="CustomConversationActions" />
+</template>
+
+<script setup lang="ts">
+import { defineComponent, h } from 'vue';
+import { ConversationActions } from '@tencentcloud/chat-uikit-vue3';
+import type { ConversationActionsProps, ConversationModel } from '@tencentcloud/chat-uikit-vue3';
+
+const CustomConversationActions = defineComponent({
+  name: 'CustomConversationActions',
+  setup(props: ConversationActionsProps) {
+    return () => h(ConversationActions, {
+      ...props,
+      customConversationActions: {
+        'custom-actions-1': {
+          label: 'custom-actions',
+          onClick: (conversation: ConversationModel) => {
+            console.log(conversation);
+          },
+        },
+      }
+    });
+  }
+});
+</script>
+```
+
+### UI Customization
+
+You can customize the popup trigger button style through the `PopupIcon` parameter, and customize the popup content through `PopupElements`.
+
+**Example: Custom Trigger Button**
+``` typescript
+<template>
+  <ConversationList :ConversationActions="CustomConversationActions" />
+</template>
+
+<script setup lang="ts">
+import { defineComponent, h } from 'vue';
+import { ConversationActions } from '@tencentcloud/chat-uikit-vue3';
+import type { ConversationActionsProps } from '@tencentcloud/chat-uikit-vue3';
+
+const CustomConversationActions = defineComponent({
+  name: 'CustomConversationActions',
+  setup(props: ConversationActionsProps) {
+    const customIcon = h('div', '自定义 Icon');
+
+    return () => h(ConversationActions, {
+      ...props,
+      PopupIcon: customIcon
+    });
+  }
+});
+</script>
+```