@tencent-rtc/mcp 1.4.7 → 1.6.0

package/resource/knowledge/chat/preset/vue/features/chat-header.md

@@ -0,0 +1,331 @@
+## Overview
+
+`ChatHeader` is the top navigation component of the chat UI. It displays basic information about the active conversation, including the conversation title, avatar, online status, and typing indicators. The component uses a container pattern and provides flexible slots for customizing the left and right action areas.
+
+## Props Quick Reference
+
+| Field | Type | Default | Description |
+|---------|---------|---------|---------|
+| title | string | undefined | Custom title; falls back to conversation info when not provided. |
+| avatarUrl | string | undefined | Custom avatar image URL. |
+| enableUserStatus | boolean | false | Whether to show user online status. |
+| enableCall | bool | false | Whether to show audio/video call buttons. |
+
+## Slots Quick Reference
+
+| Name | Description |
+|---------|---------|
+| ChatHeaderLeft | Custom content area on the left side of `ChatHeader`. |
+| ChatHeaderRight | Custom content area on the right side of `ChatHeader`. |
+
+## Detailed Props
+
+### title
+- **Type**: `string`
+
+- **Description**: Custom conversation title. When not provided, the component automatically displays the appropriate title based on conversation type (user nickname or remark for C2C; group name for group chats). Default: `undefined`.
+
+### avatarUrl
+- **Type**: `string`
+
+- **Description**: Custom avatar image URL. When not provided, the component automatically displays the appropriate avatar based on conversation type (user avatar for C2C; group avatar for group chats). Default: `undefined`.
+
+### enableUserStatus
+- **Type**: `boolean`
+
+- **Description**: Whether to enable and display user online status. Applies only in one-to-one (C2C) conversations. When enabled, shows the user's online/offline status. Default: `false`.
+
+### enableCall
+- **Type**: `boolean`
+
+- **Description**: Whether to enable and display audio/video call buttons. Default: `false`.
+
+- **Note**: Showing call buttons does not mean calls can be initiated. CallKit must be integrated first. See [Integrating TUICallKit](#integrating-tuicallkit).
+
+## Slots Reference
+
+### ChatHeaderLeft
+
+**Description**: Left-side slot for custom header content, typically used for navigation controls such as a back button or menu button.
+
+#### Example: Custom left navigation area
+``` typescript
+<template>
+  <ChatHeader>
+    <template #ChatHeaderLeft>
+      <!-- Back button: clear the active conversation -->
+      <button
+        class="nav-button"
+        @click="handleBack"
+      >
+        ⬅️
+      </button>
+    </template>
+  </ChatHeader>
+</template>
+
+<script setup lang="ts">
+import { ChatHeader, useChatContext } from '@tencentcloud/chat-uikit-vue3';
+
+const { setActiveConversation } = useChatContext();
+
+const handleBack = () => {
+  // Clear the active conversation ID
+  setActiveConversation('');
+};
+</script>
+
+<style scoped>
+.header-left-actions {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+}
+
+.nav-button {
+  width: 32px;
+  height: 32px;
+  border: none;
+  background: transparent;
+  border-radius: 4px;
+  cursor: pointer;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  transition: background-color 0.2s;
+}
+
+.nav-button:hover {
+  background-color: rgba(0, 0, 0, 0.05);
+}
+</style>
+```
+
+### ChatHeaderRight
+
+**Description**: Right-side slot for custom header content, typically used for action buttons or menus.
+
+#### Example: Integrate `ChatSetting` via `ChatHeaderRight` slot and a drawer component
+
+**App.vue**
+``` typescript
+<template>
+  <div class="chat-container">
+    <Chat>
+      <ChatHeader>
+        <template #ChatHeaderRight>
+          <!-- Settings button: open chat settings panel -->
+          <button
+            class="nav-button"
+            @click="setIsSettingOpen(true)"
+          >
+            ⚙️
+          </button>
+        </template>
+      </ChatHeader>
+      <MessageList />
+      <MessageInput />
+    </Chat>
+    <Drawer
+      :open="isChatSettingOpen"
+      @close="setIsSettingOpen(false)"
+    >
+      <ChatSetting style="flex: 1;" />
+    </Drawer>
+  </div>
+</template>
+
+<script setup lang="ts">
+import {
+  Chat,
+  ChatHeader,
+  MessageList,
+  MessageInput,
+  ChatSetting
+} from '@tencentcloud/chat-uikit-vue3';
+import { Drawer } from './components/Drawer.vue';
+
+// State management
+const isChatSettingOpen = ref(false);
+
+const setIsSettingOpen = (isOpen: boolean) => {
+  isChatSettingOpen.value = isOpen;
+};
+</script>
+
+<style scoped>
+.chat-container {
+  display: flex;
+  flex-direction: column;
+  height: 100vh;
+}
+</style>
+
+```
+
+**Drawer.vue**
+``` typescript
+<script setup lang="ts">
+import { computed, nextTick, ref, watch } from 'vue';
+import type { PropType } from 'vue';
+
+const props = defineProps({
+  open: { type: Boolean, required: true },
+  placement: {
+    type: String as PropType<'right' | 'left' | 'bottom'>,
+    default: 'right',
+  },
+  duration: { type: Number, default: 300 },
+  container: {
+    type: [String, Object] as PropType<string | HTMLElement>,
+    default: 'body',
+  },
+  zIndex: { type: Number, default: 1000 },
+  maskClosable: { type: Boolean, default: true },
+});
+
+const emit = defineEmits<{
+  (e: 'close'): void;
+}>();
+
+const isRendered = ref(false);
+const isVisible = ref(false);
+const isAnimating = ref(false);
+
+const containerTarget = computed(() => props.container ?? 'body');
+const cssVars = computed(() => ({
+  '--duration': `${props.duration}ms`,
+  '--z-index': String(props.zIndex),
+}));
+
+watch(
+  () => props.open,
+  async (nextOpen) => {
+    if (nextOpen) {
+      // open drawer
+      if (!isRendered.value) {
+        isRendered.value = true;
+      }
+      // wait for DOM render
+      await nextTick();
+      // force repaint, ensure initial state is applied
+      requestAnimationFrame(() => {
+        isVisible.value = true;
+        isAnimating.value = true;
+      });
+    } else {
+      // close drawer
+      isVisible.value = false;
+      isAnimating.value = true;
+    }
+  },
+  { immediate: true },
+);
+
+function onMaskClick() {
+  if (props.maskClosable) {
+    emit('close');
+  }
+}
+
+function handlePanelTransitionEnd(e: TransitionEvent) {
+  if (e.propertyName !== 'transform') {
+    return;
+  }
+  isAnimating.value = false;
+  if (!isVisible.value) {
+    isRendered.value = false;
+  }
+}
+
+function handleMaskTransitionEnd(e: TransitionEvent) {
+  if (e.propertyName !== 'opacity') {
+    // mask animation end
+  }
+}
+</script>
+
+<template>
+  <Teleport :to="containerTarget">
+    <div
+      v-if="isRendered"
+      :class="[$style.wrapper, isVisible ? $style['wrapper-open'] : '']"
+      :style="cssVars"
+    >
+      <div
+        :class="[$style.mask, isVisible ? $style['mask-open'] : '']"
+        @click="onMaskClick"
+        @transitionend="handleMaskTransitionEnd"
+      />
+      <div
+        :class="[
+          $style.panel,
+          $style[`from-${props.placement}`],
+          isVisible ? $style['panel-open'] : ''
+        ]"
+        @click.stop
+        @transitionend="handlePanelTransitionEnd"
+      >
+        <slot />
+      </div>
+    </div>
+  </Teleport>
+</template>
+
+<style module lang="scss">
+.wrapper{position:fixed;inset:0;z-index:var(--z-index);pointer-events:none;}.wrapper-open{pointer-events:auto;}.mask{position:absolute;inset:0;background:rgba(0,0,0,0.45);opacity:0;transition:opacity var(--duration) ease;pointer-events:auto;}.mask-open{opacity:1;}.panel{position:absolute;background:var(--bg-color-operate);max-width:100%;max-height:100%;transition:transform var(--duration) ease;pointer-events:auto;box-shadow:0 8px 16px rgba(0,0,0,0.15);display:flex;flex-direction:row;}.from-right{top:0;right:0;height:100%;width:320px;transform:translateX(100%);}.from-left{top:0;left:0;height:100%;width:320px;transform:translateX(-100%);}.from-bottom{left:0;bottom:0;width:100%;height:40%;transform:translateY(100%);}.panel-open.from-right,.panel-open.from-left,.panel-open.from-bottom{transform:translate(0,0);}
+</style>
+
+```
+
+## Integrating TUICallKit
+
+Install `@tencentcloud/call-uikit-vue` and import it in your project. For more information, see [Audio/Video Calling (with UI)](https://cloud.tencent.com/document/product/647/78742).
+``` typescript
+<script lang="ts" setup>
+import { Teleport } from 'vue';
+import { TUICallKit } from '@tencentcloud/call-uikit-vue';
+<script>
+
+<template>
+  <UIKitProvider>
+    <Teleport to="body">
+      <TUICallKit
+        style="
+          position: fixed;
+          width: 600px;
+          height: 400px;
+          top: 50%;
+          left: 50%;
+          transform: translate(-50%, -50%);
+          z-index: 1000;
+        "
+      />
+    </Teleport>
+    // other code ...
+  </UIKitProvider>
+<template>
+```
+
+## Related Documentation
+- Custom Components - Chat Container
+
+- Custom Components - UIKitProvider
+
+- Custom Components - ConversationList
+
+- Custom Components - MessageList
+
+- Custom Components - MessageInput
+
+- Custom Components - ChatSetting
+
+- Custom Components - ContactList
+
+- Custom Components - Search
+
+- [chat-uikit-vue3 npm](https://www.npmjs.com/package/@tencentcloud/chat-uikit-vue3)
+
+- [GitHub Demo](https://github.com/Tencent-RTC/TUIKit_Vue3/tree/main/demos/rtcube-vite-vue3)
+
+## Community and Feedback

package/resource/knowledge/chat/preset/vue/features/chat-setting.md

@@ -0,0 +1,79 @@
+## Component Overview
+
+`ChatSetting` is a smart chat settings component that automatically renders the appropriate settings UI based on the currently active conversation type. It integrates both C2C (one-to-one) chat settings and group chat settings, providing a unified entry point for chat configuration.
+
+Core characteristics:
+- **Auto-adaptation**: Automatically switches the settings UI based on conversation type (one-to-one or group chat).
+
+- **State-driven**: Content updates automatically based on the currently active conversation state.
+
+   > **Note:**
+   >
+
+   > The component is not displayed when no conversation is active.
+   >
+
+## Quick Start
+
+`ChatSetting` is a standalone component you can use freely. For flexibility, UIKit does not provide a default integration pattern.
+
+The recommended approach is to combine it with the `ChatHeaderRight` slot on `ChatHeader` to control `ChatSetting` visibility. Example:
+``` typescript
+<template>
+  <UIKitProvider>
+    <Chat>
+      <ChatHeader>
+        <template #ChatHeaderRight>
+          <button @click="toggleChatSetting">
+            ⚙️ Settings
+          </button>
+        </template>
+      </ChatHeader>
+      <MessageList />
+      <MessageInput />
+    </Chat>
+    <Drawer
+      :open="isSettingVisible"
+      title="Chat Settings"
+    >
+      <ChatSetting />
+    </Drawer>
+  </UIKitProvider>
+</template>
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { ChatHeader } from '@tencentcloud/chat-uikit-vue3';
+// Assume you have a Drawer component
+import { Drawer } from 'your-ui-library';
+
+const isSettingVisible = ref(false);
+
+const toggleChatSetting = () => {
+  isSettingVisible.value = !isSettingVisible.value;
+};
+</script>
+```
+
+## Related Documentation
+- Custom Components - UIKitProvider
+
+- Custom Components - ConversationList
+
+- Custom Components - Chat
+
+- Custom Components - MessageInput
+
+- Custom Components - MessageList
+
+- Custom Components - ChatSetting
+
+- Custom Components - ContactList
+
+- Custom Components - Search
+
+- [chat-uikit-vue3 npm](https://www.npmjs.com/package/@tencentcloud/chat-uikit-vue3)
+
+- [GitHub Demo](https://github.com/Tencent-RTC/TUIKit_Vue3/tree/main/demos/rtcube-vite-vue3)
+
+## Community and Feedback

package/resource/knowledge/chat/preset/vue/features/contact-list.md

@@ -0,0 +1,277 @@
+## Overview
+
+ContactList is a highly configurable contact list component. It supports friend list, group list, blocklist, and application management, offering core features such as group collapsing, search filtering, and custom rendering. It is 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 the search feature|
+|groupConfig|Partial<Record<ContactItemType, CustomGroupConfig>>|{}|Custom group configuration|
+|searchPlaceholder|string|'Search contacts'|Search box placeholder text|
+|emptyText|string|'No contacts'|Empty state prompt 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 callback|
+|onFriendApplicationAction|(action: 'accept' \| 'refuse', application: FriendApplication) => void|undefined|Friend application action callback|
+|onGroupApplicationAction|(action: 'accept' \| 'refuse', application: GroupApplication) => void|undefined|Group application action callback|
+
+## 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|Blocklist 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 blocklist event|
+|removeFromBlacklist|(profile: UserProfile)|Remove from blocklist 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
+
+### Custom Contact List Search Toggle
+
+Use the `enableSearch` prop to control whether friend and group search is shown in `ContactList`.
+``` typescript
+<template>
+  <ContactList :enableSearch="false" />
+</template>
+```
+
+|enableSearch="true"|enableSearch="false"|
+|---------|---------|
+|<br>|<br>|
+
+### Custom Contact List Group Configuration
+
+Use `groupConfig` to customize group settings, including title, display order, and hidden groups.
+``` 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|
+|---------|---------|
+|<br>|<br>|
+
+### Custom Contact List Item
+
+Pass a custom `ContactItem` component to fully control how each contact list item is rendered.
+``` 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 |
+| --- | --- |
+|  |  |
+
+### Custom Contact Detail Action Toggle
+
+Use the `showActions` prop to control whether action buttons are shown on the contact detail page.
+``` typescript
+<template>
+  <ContactInfo
+    :showActions="false"
+  />
+</template>
+```
+| Before | After |
+| --- | --- |
+|  |  |
+
+### Custom Contact Detail Empty State
+
+When no contact is selected, you can customize the empty state component.
+``` 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>
+```
+
+### Custom Friend Detail Component
+
+You can customize the detail view component for different contact types.
+``` typescript
+<template>
+  <div class="custom-contact-info">
+    <label>Custom friend detail</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 |
+| --- | --- |
+|  |  |