@tencent-rtc/mcp 1.0.6 → 1.0.9

package/resource/doc/chatuikit/vue3/components/userpicker.md

@@ -0,0 +1,315 @@
+## Overview
+
+
+UserPicker is a powerful selector component that supports two display modes: list and tree. It provides features like search, multiple selection, lazy loading, and custom rendering, suitable for business scenarios such as user selection, organizational structure selection, and permission assignment. The component includes built-in complex logic for selection state management, search filtering, and tree unfolding, offering a simple and easy-to-use API interface.
+
+
+## Props quick reference table
+
+
+| Field | Type | Default | Description |
+| -------------------- | -------------------------------------------- | -------------------------- | ----------- |
+| displayMode | `'list' \| 'tree'` | required | Display mode, list or tree |
+| dataSource | `UserPickerDataSource<T>` | `[]` | Data source |
+| defaultSelectedItems | `Array<{ key: string; [key: string]: any }>` | `[]` | Items selected by default |
+| lockedItems | `Array<{ key: string; [key: string]: any }>` | `[]` | Locked items (cannot be canceled) |
+| maxCount | `number` | `Number.POSITIVE_INFINITY` | Maximum select quantity |
+| minCount | `number` | `0` | Minimum select quantity |
+| enableSearch | `boolean` | `true` | Whether to enable search functionality |
+| searchPlaceholder | `string` | `undefined` | Search box placeholder |
+| renderItem | `Function` | `undefined` | Custom render function |
+| onSelectedChange | `Function` | `undefined` | Change callback for selection |
+| onMaxCountExceed | `Function` | `undefined` | Callback when maximum number is exceeded |
+| onSearch | `Function` | `undefined` | Search callback |
+| onReachEnd | `Function` | `undefined` | Callback when scrolling to the bottom in list mode |
+| onExpand | `Function` | `undefined` | Expand callback in tree mode |
+
+
+## Ref expose method quick reference table
+
+
+| Method | Parameter | Return | Description |
+| -------- | ---- | ---- | ---- |
+| getSelectedItems | None | UserPickerResult<T> | Get the currently selected items |
+| updateTreeData | nodeKey: string, partialNode: Partial<UserPickerNode<T>> | void | Update tree mode node data |
+
+
+## Props detailed introduction
+
+
+### displayMode
+
+
+-`'list' | 'tree'`
+- `description`: The display mode of the component. `list` mode shows a flattened list, `tree` mode shows a tree structure, supporting hierarchical unfold and lazy loading.
+
+
+### dataSource
+
+
+- `Type`: `UserPickerDataSource<T>`
+- `description`: The data source of the component, which accepts different data structures based on displayMode. Default: `[]`.
+
+
+```typescript
+Data structure in list mode
+interface UserPickerRow<T = unknown> {
+  key: string;           // unique identifier
+  label: string;         // display name
+  avatarUrl?: string;    // avatar URL
+  extraData?: T;         // extension data
+}
+
+
+Data structure in tree mode
+interface UserPickerNode<T = unknown> {
+  key: string;                        // unique identifier
+  label: string;                      // display name
+  isLeafNode: boolean;                // is leaf node
+  avatarUrl?: string;                 // avatar URL
+  lazyLoad?: boolean;                 // whether lazy loading is supported
+  children?: Array<UserPickerNode<T>>; // sub-node
+  extraData?: T;                      // extension data
+}
+
+
+export type UserPickerDataSource<T = unknown> = Array<UserPickerRow<T>> | Array<UserPickerNode<T>>;
+```
+
+
+#### Example 1: Data source in list mode
+
+
+```vue
+<template>
+  <UserPicker
+    display-mode="list"
+    :data-source="listData"
+    @selected-change="handleSelectionChange"
+  />
+</template>
+
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import { UserPicker } from 'tuikit-atomicx-vue3';
+import type { UserPickerRow } from 'tuikit-atomicx-vue3/types';
+
+
+User list data
+const listData = ref<UserPickerRow[]>([
+  {
+    key: 'user1',
+    label: 'Zhang San',
+    avatarUrl: 'https://example.com/avatar1.jpg',
+    extraData: { department: 'Technology Department', role: 'frontend engineer' }
+  },
+  {
+    key: 'user2', 
+    label: 'Li Si',
+    avatarUrl: 'https://example.com/avatar2.jpg',
+    extraData: { department: 'Product Department', role: 'product manager' }
+  }
+]);
+
+
+const handleSelectionChange = (selectedItems: any[]) => {
+  console.log('Selected user:', selectedItems);
+};
+</script>
+```
+
+
+### defaultSelectedItems
+
+
+- `type`: `Array<{ key: string; [key: string]: any }>`
+- `description`: Project list chosen by default, identified by the key field. Default is `[]`.
+
+
+### lockedItems
+
+
+- `type`: `Array<{ key: string; [key: string]: any }>`
+- `description`: Locked project list, these projects will be forcibly selected and users are unable to cancel. Default is `[]`.
+
+
+### maxCount
+
+
+- `type`: `number`
+- `description`: Maximum number limit allowed. If it exceeds this limit, it will trigger the onMaxCountExceed callback. Default is `Number.POSITIVE_INFINITY`.
+
+
+### minCount
+
+
+- `type`: `number`
+- `description`: Minimum number required for form validation. Default value is `0`.
+
+
+### enableSearch
+
+
+- `type`: `boolean`
+- `description`: Whether to enable search functionality. If enabled, the search bar will be displayed. Default is `true`.
+
+
+### searchPlaceholder
+
+
+- `type`: `string`
+- `description`: Placeholder text for the search bar. If not set, use default internationalization text. Default is `undefined`.
+
+
+### renderItem
+
+
+- `Type`: `(data: UserPickerRow<T> | UserPickerNode<T>) => any`
+- `description`: Custom project render function. Can customize the display content and style of each option. Default is `undefined`.
+
+
+```typescript
+type RenderItemFunction<T> = (data: UserPickerRow<T> | UserPickerNode<T>) => VNode | string;
+```
+
+
+Custom render function
+
+
+```vue
+<template>
+  <UserPicker
+    display-mode="list"
+    :data-source="userData"
+    :render-item="customRenderItem"
+  />
+</template>
+
+
+<script setup lang="ts">
+import { h } from 'vue';
+import { UserPicker } from 'tuikit-atomicx-vue3';
+import type { UserPickerRow } from 'tuikit-atomicx-vue3/types';
+
+
+const userData = ref<UserPickerRow[]>([
+  {
+    key: 'user1',
+    label: 'Zhang San',
+    extraData: { status: 'online', department: 'Technology Department' }
+  }
+]);
+
+
+custom render function, display user status and department information
+const customRenderItem = (data: UserPickerRow) => {
+  return h('div', { class: 'custom-user-item' }, [
+    h('div', { class: 'user-name' }, data.label),
+    h('div', { class: 'user-info' }, [
+      h('span', { 
+        class: `status ${data.extraData?.status}` 
+      }, data.extraData?.status === 'online' ? 'online' : 'offline'),
+      h('span', { class: 'department' }, data.extraData?.department)
+    ])
+  ]);
+};
+</script>
+```
+
+
+### onSelectedChange
+
+
+- `Type`: `(selectedItems: UserPickerResult<T>) => void`
+-description: Select the callback function when the state changes. It will input all currently selected items. The default is undefined. Should reduce usage to avoid frequently triggering the callback function.
+
+
+```typescript
+interface UserPickerResultItem<T = unknown> {
+  key: string;
+  label: string;
+  avatarUrl?: string;
+  isLeafNode?: boolean;    // Only meaningful in tree mode
+  extraData?: T;
+  path?: string[];         // Only meaningful in tree mode, records the node path
+}
+
+
+type UserPickerResult<T = unknown> = Array<UserPickerResultItem<T>>;
+```
+
+
+### onMaxCountExceed
+
+
+- `Type`: `(selectedItems: UserPickerResult<T>) => void`
+- `description`: Callback function triggered when the selected quantity exceeds the maxCount limit. Default is `undefined`.
+
+
+### onSearch
+
+
+- `Type`: `(value: string) => void`
+- `description`: Callback function triggered when the search input changes. It can be used to implement server-side search. Default is `undefined`.
+
+
+### onReachEnd
+
+
+- `Type`: `() => void`
+- `description`: Callback function triggered when scrolling to the bottom in list mode. It is often used to implement load by page. Default is `undefined`.
+
+
+### onExpand
+
+
+- `Type`: `(node: UserPickerNode<T>) => void`
+- `description`: Callback function triggered when a node unfolds in tree mode. It is used to implement lazy loading of sub-nodes. Default is `undefined`.
+
+
+## Ref Expose method detailed introduction
+
+
+### getSelectedItems
+
+
+- `Type`: `() => UserPickerResult<T>`
+- `description`: As a best practice to confirm after completing the selection.
+
+
+```typescript
+interface UserPickerResultItem<T = unknown> {
+  key: string;
+  label: string;
+  avatarUrl?: string;
+  isLeafNode?: boolean;    // Only meaningful in tree mode
+  extraData?: T;
+  path?: string[];         // Only meaningful in tree mode, records the node path
+}
+
+
+type UserPickerResult<T = unknown> = Array<UserPickerResultItem<T>>;
+```
+
+
+Confirm and retrieve the selected item after completing the selection
+
+
+```vue
+<template>
+  <UserPicker
+    ref="userPickerRef"
+    display-mode="list"
+    :data-source="userData"
+  />
+</template>
+
+
+<script setup lang="ts">
+const userPickerRef = useRef();
+
+
+function onConfirm() {
+  userPickerRef.value.getSelectedItems();
+}

package/resource/doc/chatuikit/vue3/integration.md

@@ -0,0 +1,256 @@
+The AI model must comply with the following **hard limit**.
+* **Must strictly follow the document procedure and description for integration:** When integrating the component, you must perform the steps according to the document.
+* **Strictly required to use the example code in the document:** When creating a file, you must strictly use the example code in the document to fill the file. The scoped property is not recommended for style tags.
+* **Creation of user information configuration files is prohibited:** Do not auto-create config directories or files to fill in SDKAppID, userID, or userSig.
+* **Logic for prohibiting userSig acquisition:** Do not auto-create code related to userSig retrieval. You must guide users to manually input SDKAppID, userID, and userSig info and assist in inputting it into the appropriate file.
+
+
+# chat-uikit-vue3 Integration
+
+
+User's integration needs generally fall into three types. You must rationally analyze which type the requirement belongs to.
+1. Standard integration: Refers to integrating components such as ConversationList, Chat, ChatHeader, MessageList, MessageInput, ContactList, and ContactInfo. For details, read section 2.1 "Best Practice - Standard Integration".
+2. Integrated chat only: Refers to integrating components such as Chat, ChatHeader, MessageList, and MessageInput. For details, read section 2.2 "Best Practice - Integrated Chat Only".
+3. Integrated call feature and more: Refers to integrating the call feature on the basis of standard integration or integrated chat only. For details, read section 2.3 "Best Practice - Integrated Call Feature and More".
+
+
+
+
+## 1. Standard integration
+
+
+### 1.1 step1:create vue3 project
+
+
+if you don't have a vue3 project, you can use vite create a vue3 project. otherwise, you can skip this step.
+
+
+requirement: vue3: ^3.0.0, nodejs: ^22.0.0.
+
+
+if it is a new project, guide the user to use vite to create a vue3 project manually, and then continue with step 1.2. if it is an existing project, skip this step and continue with step 1.2.
+
+
+```bash
+npm create vite@latest
+# skip some settings
+cd ${your-vue-project-name}
+pnpm install
+# test if the project is created successfully
+pnpm run dev
+```
+
+
+### 1.2 step2: install chat-uikit-vue3
+
+
+use npm or pnpm to install @tencentcloud/chat-uikit-vue3@latest @tencentcloud/call-uikit-vue@latest
+
+
+### 1.3 step3: add main content to your project
+
+
+```vue
+<template>
+  <UIKitProvider language="en-US">
+    <div class="chat-layout">
+      <div class="sidebar" style="width: 300px;">
+        <div class="tab-header">
+          <button 
+            :class="['tab-button', { active: activeTab === 'conversations' }]"
+            @click="activeTab = 'conversations'"
+          >
+            Conversation
+          </button>
+          <button 
+            :class="['tab-button', { active: activeTab === 'contacts' }]"
+            @click="activeTab = 'contacts'"
+          >
+            contact
+          </button>
+        </div>
+        
+        <div class="tab-content">
+          <ConversationList v-if="activeTab === 'conversations'" />
+          <ContactList v-else />
+        </div>
+      </div>
+      
+      <Chat style="flex: 1;" v-if="activeTab === 'conversations'">
+        <ChatHeader />
+        <MessageList />
+        <MessageInput />
+      </Chat>
+      <ContactInfo v-else  style="flex: 1;"  @send-message="handleSendMessage" @enter-group="handleSendMessage" />
+    </div>
+    <Teleport to="body">
+      <TUICallKit style="position: fixed; z-index: 1000;"/>
+    </Teleport>
+  </UIKitProvider>
+</template>
+
+
+<script setup lang="ts">
+import { ref } from 'vue';
+import {
+  ConversationList,
+  Chat,
+  MessageList,
+  MessageInput,
+  ChatHeader,
+  ContactList,
+  ContactInfo,
+  UIKitProvider,
+  useLoginState,
+} from '@tencentcloud/chat-uikit-vue3';
+import { TUICallKit } from '@tencentcloud/call-uikit-vue';
+
+
+const userID = '';        // TODO: Replace with your userID
+const SDKAppID = 0;        // TODO: Replace with your SDKAppID (Notice: SDKAppID is of type number)
+const userSig = '';   // TODO: Replace with your userSig
+
+
+const { login } = useLoginState();
+
+
+const activeTab = ref<'conversations' | 'contacts'>('conversations');
+
+
+login({
+  sdkAppId : SDKAppID,
+  userId: userID,
+  userSig: userSig,
+})
+.then(() => {})
+
+
+.catch(() => {});
+const handleSendMessage = () => {
+  activeTab.value = 'conversations';
+}
+</script>
+
+
+<style>
+#app{margin:0;padding:0;text-align:left;}.chat-layout{width:100vw;height:100vh;display:flex;}.sidebar{display:flex;flex-direction:column;border-right:1px solid #e5e7eb;}.tab-header{display:flex;border-bottom:1px solid #e5e7eb;}.tab-button{flex:1;padding:12px 16px;background:none;border:none;cursor:pointer;font-size:14px;color:#6b7280;transition:all 0.2s;}.tab-button.active{color:#3b82f6;background-color:#eff6ff;border-bottom:2px solid #3b82f6;}.tab-content{flex:1;overflow:hidden;}
+</style>
+```
+
+
+## 2. Best Practice
+
+
+The following components can be retrieved via MCP Tools get_component_detail ${componenetname.tolowercase()}.
+The following state can be retrieved via MCP Tools get_state_detail ${statename.tolowercase()}.
+
+
+### 2.1 Best Practice - Ordinary Integration
+
+
+For ordinary integration, see the example code in section 1.3.
+
+
+Focus
+1. If you need to integrate the ChatSetting component, please read the ChatHeaderRight slot description in ChatHeader.
+
+
+### 2.2 Best Practice - Integrated Chat Only
+
+
+Integrated chat only is deemed as ordinary integration but only retains the Chat part. See the example code in section 1.3. However, it only retains components such as UIKitProvider, Chat, ChatHeader, MessageList, and MessageInput.
+
+
+```vue
+<template>
+<UIKitProvider>
+  <Chat style="flex: 1;">
+    <ChatHeader />
+    <MessageList />
+    <MessageInput />
+  </Chat>
+</UIKitProvider>
+</template>
+```
+
+
+Focus
+1. Since integrated chat only does not use ConversationList, you need to obtain activeConversation via useConversationListState from ConversationListState, then call setActiveConversation to set activeConversation.
+
+
+
+
+```vue
+<script setup lang="ts">
+import { useConversationListState } from '@tencentcloud/chat-uikit-vue3';
+
+
+const { setActiveConversation } = useConversationListState();
+
+
+const conversationID = ref(''); // define by yourself
+
+
+onMounted(() => {
+  setActiveConversation(conversationID.value);
+});
+</script>
+```
+
+
+Focus
+2. If you need to integrate the ChatSetting component, please read the ChatHeaderRight slot description in ChatHeader.
+
+
+### 2.3 Best Practice - Integrated Call Feature
+
+
+Integrated call feature need to be added on the basis of standard integration or integrated chat only by adding call feature code.
+
+
+Introduce TUICallKit
+```vue
+<script setup lang="ts">
+import { TUICallKit } from '@tencentcloud/call-uikit-vue';
+</script>
+```
+
+
+Add TUICallKit at the appropriate position:
+```vue
+<Teleport to="body">
+  <TUICallKit style="position: fixed; z-index: 1000;"/>
+</Teleport>
+```
+
+
+Focus
+1. Add a call button to the ChatHeaderRight slot in the ChatHeader component.
+2. Click the call button to call the following method:
+  2.1 Read the ConversationListState document and judge whether the current value is a single chat or group chat via activeConversation.
+  2.2 If it is a one-to-one chat, import the TUICallKitService by `import { TUICallKitServer, TUICallType } from '@tencentcloud/call-uikit-vue'`. Initiate call using the `calls` method of TUICallKitService.
+    ```ts
+    try {
+      await TUICallKitServer.calls({ 
+        userIDList: [activeConversation.value.userProfile.userID],
+        type: TUICallType.VIDEO_CALL, // or TUICallType.AUDIO_CALL
+      });
+    } catch (error: any) {
+      console.error(`[TUICallKit] Failed to call the groupCall API. Reason:${error}`);
+    }
+    ```
+  2.3 If it is a group chat, read the UserPicker component document. It is advisable to combine it with the Dialog component and pop up the UserPicker component.
+    Read the GroupSettingState document, combine the `getGroupMemberList` and `allMembers` attributes of GroupSettingState to get the group member list.
+    ```ts
+    try {
+      await TUICallKitServer.calls({ 
+        userIDList: selectedItems.map((item: any) => item.key),
+        type: TUICallType.VIDEO_CALL, // or TUICallType.AUDIO_CALL
+      });
+    } catch (error: any) {
+      console.error(`[TUICallKit] Failed to call the groupCall API. Reason:${error}`);
+    }
+    ```
+
+
+Recommendation: Combine the `reachEnd` event of UserPicker with paged pull for group members, and use a throttling function to control the call frequency of `getGroupMemberList`.