@tencent-rtc/mcp 1.3.9 → 1.4.0

package/resource/doc/{chatuikit → chatkit}/react/components/message-list.md

@@ -2,188 +2,42 @@
 
 MessageList is a powerful chat message list component with complete message display, interaction, and custom function. The component support includes message grouping, read receipt, message manipulation, scroll control, and other core chat features, while providing various custom options to satisfy different business needs.
 
-
 ## Props Configuration
-<table>
-<tr>
-<td rowspan="1" colSpan="1">Field</td>
-
-
-<td rowspan="1" colSpan="1">Type</td>
-
-
-<td rowspan="1" colSpan="1">Default Value</td>
-
-
-<td rowspan="1" colSpan="1">Description</td>
-</tr>
-
-
-<tr>
-<td rowspan="1" colSpan="1" >[alignment](https://write.woa.com/document/181344255270170624)</td>
-
-
-<td rowspan="1" colSpan="1" >'left' \| 'right' \| 'two-sided'</td>
-
-
-<td rowspan="1" colSpan="1" >'two-sided'</td>
-
-
-<td rowspan="1" colSpan="1">Message alignment mode.<br>- left: Align all messages to the left.<br>- right: Align all messages to the right.<br>- two-sided: Right-align sent messages and left-align received messages.</td>
-</tr>
-
-
-<tr>
-<td rowspan="1" colSpan="1" >[enableReadReceipt](https://write.woa.com/document/181344255270170624)</td>
-
-
-<td rowspan="1" colSpan="1" >boolean</td>
-
-
-<td rowspan="1" colSpan="1" >false</td>
-
-
-<td rowspan="1" colSpan="1">Whether to enable the read receipt feature.</td>
-</tr>
-
-
-<tr>
-<td rowspan="1" colSpan="1" >[messageActionList](https://write.woa.com/document/181344255270170624)</td>
-
-
-<td rowspan="1" colSpan="1" >IMessageAction[]</td>
-
-
-<td rowspan="1" colSpan="1" >undefined</td>
-
-
-<td rowspan="1" colSpan="1">Custom message operation list, such as copy, revoke, delete.</td>
-</tr>
-
-
-<tr>
-<td rowspan="1" colSpan="1" >[messageAggregationTime](https://write.woa.com/document/181344255270170624)</td>
-
-
-<td rowspan="1" colSpan="1" >number</td>
-
-
-<td rowspan="1" colSpan="1">300 (5 minutes)</td>
-
-
-<td rowspan="1" colSpan="1">Message aggregation interval (seconds). Consecutive messages from the same sender within this period will be aggregated and displayed.</td>
-</tr>
-
-
-<tr>
-<td rowspan="1" colSpan="1" >[filter](https://write.woa.com/document/181344255270170624)</td>
-
-
-<td rowspan="1" colSpan="1" >(message: IMessageModel) => boolean</td>
-
-
-<td rowspan="1" colSpan="1" >undefined</td>
-
-
-<td rowspan="1" colSpan="1">Message filtering function, used to control which messages to display.</td>
-</tr>
-
-
-<tr>
-<td rowspan="1" colSpan="1" >[className](https://write.woa.com/document/181344255270170624)</td>
-
-
-<td rowspan="1" colSpan="1" >string</td>
-
-
-<td rowspan="1" colSpan="1" >undefined</td>
-
-
-<td rowspan="1" colSpan="1">Custom CSS class name.</td>
-</tr>
-
-
-<tr>
-<td rowspan="1" colSpan="1" >[style](https://write.woa.com/document/181344255270170624)</td>
-
-
-<td rowspan="1" colSpan="1" >React.CSSProperties</td>
-
-
-<td rowspan="1" colSpan="1" >undefined</td>
-
-
-<td rowspan="1" colSpan="1">Custom inline style.</td>
-</tr>
-
-
-<tr>
-<td rowspan="1" colSpan="1" >[Message](https://write.woa.com/document/181344255270170624)</td>
-
-
-<td rowspan="1" colSpan="1" >React.ComponentType</td>
-
-
-<td rowspan="1" colSpan="1" >Message</td>
-
-
-<td rowspan="1" colSpan="1">Custom message component.</td>
-</tr>
-
-
-<tr>
-<td rowspan="1" colSpan="1" >[MessageTimeDivider](https://write.woa.com/document/181344255270170624)</td>
-
-
-<td rowspan="1" colSpan="1" >React.ComponentType</td>
-
-
-<td rowspan="1" colSpan="1" >MessageTimeDivider</td>
-
-
-<td rowspan="1" colSpan="1">Custom time dividing line component.</td>
-</tr>
-</table>
-
-
-
+| Field | Type | Default Value | Description |
+| --- | --- | --- | --- |
+| alignment | 'left' \\| 'right' \\| 'two-sided' | 'two-sided' | Message alignment mode.<br>- left: Align all messages to the left.<br>- right: Align all messages to the right.<br>- two-sided: Right-align sent messages and left-align received messages. |
+| enableReadReceipt | boolean | false | Whether to enable the read receipt feature. |
+| messageActionList | IMessageAction[] | undefined | Custom message operation list, such as copy, revoke, delete. |
+| messageAggregationTime | number | 300 (5 minutes) | Message aggregation interval (seconds). Consecutive messages from the same sender within this period will be aggregated and displayed. |
+| filter | (message: IMessageModel) => boolean | undefined | Message filtering function, used to control which messages to display. |
+| className | string | undefined | Custom CSS class name. |
+| style | React.CSSProperties | undefined | Custom inline style. |
+| Message | React.ComponentType | Message | Custom message component. |
+| MessageTimeDivider | React.ComponentType | MessageTimeDivider | Custom time dividing line component. |
 
 ## Prop field explanation
 
-
 ### alignment
 
-
 Parameter type: `'left' | 'right' | 'two-sided'`
 
-
 alignment is used to set the message alignment mode, supporting three modes: `left`, `right`, and `two-sided`. Default value is `'two-sided'`.
 - `two-sided`: Non-person messages are on the left, my messages are on the right
 
-
 - `left`: All messages are on the left
 
-
 - `right`: All messages are on the right
 
-
-
-
 ### enableReadReceipt
 
-
 Parameter type: `boolean`
 
-
 enableReadReceipt is used to set whether the message read receipt feature is enabled. Default value: `false`.
 
-
 ### messageActionList
 
-
 Parameter type: `IMessageAction[]`
 
-
 The messageActionList is used to set the actions list of messages, such as copy, recall, and delete. The default value is the complete message operation list `['copy', 'recall', 'quote', 'forward', 'delete']`.
 ``` tsx
 interface IMessageAction {
@@ -197,18 +51,14 @@ interface IMessageAction {
 }
 ```
 
-
 Use `useMessageAction` to obtain the complete message operation list, then customize as needed.
 
-
 #### Example 1: Change the order of the action list
 
-
 Assuming the message actions list is displayed in the order: `forward`, `copy`, `recall`, `quote`, `delete`.
 ``` tsx
 import { Chat, MessageList, useMessageActions } from '@tencentcloud/chat-uikit-react';
 
-
 const App = () => {
   const actions = useMessageActions(['forward', 'copy', 'recall', 'quote', 'delete']);
   return (
@@ -219,15 +69,12 @@ const App = () => {
 }
 ```
 
-
 #### Example 2: Only show some message actions
 
-
 Only show `forward`, `copy`, `recall` operations.
 ``` tsx
 import { Chat, MessageList, useMessageActions } from '@tencentcloud/chat-uikit-react';
 
-
 const App = () => {
   const actions = useMessageActions(['forward', 'copy', 'recall']);
   return (
@@ -237,27 +84,21 @@ const App = () => {
   );
 }
 
-
 ```
 
-
 #### Example 3: Customize the style of message actions
 
-
 Here is an example of a custom recall operation:
 1. Change the tag to 'recall ⚠️'
 
-
 2. Change the color to orange
 
-
 3. Only text messages can be withdrawn
 
-
    ``` tsx
    import TUIChatEngine from '@tencentcloud/chat-uikit-engine';
    import { Chat, MessageList, useMessageActions } from '@tencentcloud/chat-uikit-react';
-   
+
    const ChatApp = () => {
      const actions = useMessageActions(['copy', {
        key: 'recall',
@@ -267,7 +108,7 @@ Here is an example of a custom recall operation:
        },
        visible: (message) => message.type === TUIChatEngine.TYPES.MSG_TEXT,
      }, 'quote', 'forward', 'delete']);
-   
+
      return (
        <Chat>
          <MessageList messageActionList={actions} />
@@ -276,16 +117,13 @@ Here is an example of a custom recall operation:
    }
    ```
 
-
 #### Example 4: Add new custom message actions
 
-
 Assuming custom message actions are required, for example, only messages sent by others can be tagged as 'like' and inserted after the 'recall' operation.
 ``` tsx
 import { useMessageAction } from '@tencentcloud/chat-uikit-react';
 import { yourApi } from '@/api/yourApi';
 
-
 const customActions = {
   key: 'like',
   label: 'Like',
@@ -299,42 +137,33 @@ const customActions = {
   }
 }
 
-
 function ChatApp() {
   const actions = useMessageAction(['forward', 'copy', 'recall', customActions, 'quote', 'delete']);
   return <MessageList messageActionList={actions} />;
 }
 ```
 
-
 ### messageAggregationTime
 
-
 Parameter type: `number`
 
-
 messageAggregationTime is used to set the message aggregation interval. Consecutive messages from the same sender will be aggregated and displayed. Default value: `300` (seconds).
 
-
 ### filter
 
-
 Parameter type: `(message: IMessageModel) => boolean`
 
-
 filter is used to set the message filtering function to control which messages to display. Default value: `undefined`.
 
-
 #### Example: Filter out error messages sent by robots
 ``` tsx
 import { MessageList } from '@/components/MessageList';
 import TUIChatEngine from '@tencentcloud/chat-uikit-engine';
 
-
 const messageFilter = (message) => {
   // Filter out text messages where sender nickname contains '_robot' and content contains 'operation-failed'
   if (
-    message.nick?.includes('_robot') 
+    message.nick?.includes('_robot')
     && message.type === TUIChatEngine.TYPES.MSG_TEXT
     && message.payload?.text?.includes('operation-failed')
   ) {
@@ -343,50 +172,37 @@ const messageFilter = (message) => {
   return true;
 };
 
-
 function ChatApp() {
   return <MessageList filter={messageFilter} />;
 }
 ```
 
-
 ### className
 
-
 Parameter type: `string`
 
-
 className is used to set the root container's custom CSS class name. Default value: `undefined`.
 
-
 ### style
 
-
 Parameter type: `React.CSSProperties`
 
-
 style is used to set the root container's custom inline style. Default value: `undefined`.
 
-
 ### Message
 
-
 Parameter type: `React.ComponentType`
 
-
 Message is used to set the custom message component, replacing the default message rendering component. Default value: built-in `Message` component.
 
-
 #### Example: Custom CUSTOM message click redirection component of messages
 ``` tsx
 import TUIChatEngine from '@tencentcloud/chat-uikit-engine';
 import { Chat, MessageList, Message } from '@tencentcloud/chat-uikit-react';
 
-
 function CustomMessage(props) {
   const { message } = props;
 
-
   if (message.type === TUIChatEngine.TYPES.MSG_CUSTOM) {
     const { businessID, ...restData } = JSON.parse(message.payload.data);
     if (businessID === 'text_link') {
@@ -405,7 +221,6 @@ function CustomMessage(props) {
   }
 }
 
-
 function ChatApp() {
   return (
     <Chat>
@@ -415,44 +230,39 @@ function ChatApp() {
 }
 ```
 
-
 ### MessageTimeDivider
 
-
 Parameter type: `React.ComponentType`
 
-
 MessageTimeDivider is used to set the custom time dividing line component. Default value: built-in `MessageTimeDivider` component.
 
-
 #### Example: Case-sensitive working hour dividing line
 ``` tsx
 import { Chat, MessageList, MessageTimeDivider } from '@tencentcloud/chat-uikit-react';
 
-
 const BusinessTimeDivider: typeof MessageTimeDivider = ({ prevMessage, currentMessage }) => {
   if (!prevMessage || !currentMessage) return null;
-  
+
   For each message to be rendered, get the current and previous message time, convert them to date objects, and determine whether they cross days or exceed a 4-hour interval.
   const currentTime = new Date(currentMessage.time * 1000);
   const prevTime = new Date(prevMessage.time * 1000);
-  
+
   // Display only when crossing days or the interval exceeds 4 hours
   const shouldShow = currentTime.toDateString() !== prevTime.toDateString() ||
                     (currentTime.getTime() - prevTime.getTime()) > 4 * 60 * 60 * 1000;
-  
+
   if (!shouldShow) return null;
-  
+
   Check working hours (9:00-18:00, Monday through Friday)
   const isWorkingTime = () => {
     const hour = currentTime.getHours();
     const day = currentTime.getDay();
     return day >= 1 && day <= 5 && hour >= 9 && hour <= 18;
   };
-  
+
   const timeLabel = isWorkingTime() ? 'working hour' : 'off hours';
   const timeColor = isWorkingTime() ? '#52c41a' : '#faad14';
-  
+
   return (
     <div style={{ textAlign: 'center', margin: '16px 0' }}>
       <span style={{
@@ -469,7 +279,6 @@ const BusinessTimeDivider: typeof MessageTimeDivider = ({ prevMessage, currentMe
   );
 };
 
-
 function ChatApp() {
   return (
     <Chat>
@@ -479,7 +288,6 @@ function ChatApp() {
 }
 ```
 
-
 ## Summary
 
 The MessageList component provides complete message list functionality and various custom options. By reasonably configuring Props and custom components, you can create a chat interface that meets business requirements. It is advisable to select appropriate configuration based on specific scenarios in actual use.

package/resource/doc/chatkit/react/components/search.md

@@ -0,0 +1,243 @@
+## Component Overview
+
+Search is a complete search solution with a full set of components, including search bar, result display, advanced search, and other features. It is suitable for user, group, and message search in instant messaging, online meeting, and online education scenarios.
+
+> **Note:**
+>
+
+> Note: This feature belongs to VAS. You need to purchase cloud search plugin. Please click [purchase](https://console.trtc.io/chat/plugin/TUICloudSearch).
+>
+
+## Component Architecture
+``` bash
+Search (main component)
+├── SearchBar              # Search bar component
+├── SearchResults          # Search result component
+├── SearchAdvanced         # Advanced search component
+└── SearchResultsItem      # Search result item component
+    ├── User               # User result item
+    ├── Group              # Group result item
+    ├── Message            # Message result item
+    └── Conversation       # Session result item
+```
+
+## Search Mode
+| **Mini Mode** | **Standard Mode** | **Embedded Mode** |
+| --- | --- | --- |
+| - Suitable for sidebar or small container<br>- Display finite number of results<br>- Support expand to view more | - Suitable for full-screen search UI<br>- Feature demonstration<br>- Advanced Search Support | - Suitable for chat UI<br>- Focus on message search<br>- Optimized layout |
+|  |  |  |
+
+## Props
+| Attribute Name | Type | Default Value | Description |
+| --- | --- | --- | --- |
+| variant | VariantType | VariantType.MINI | Search mode: mini, standard, embedded |
+| SearchBar | React.ComponentType<SearchBarProps> | DefaultSearchBar | Custom search box component |
+| SearchResults | React.ComponentType<SearchResultsProps> | DefaultSearchResults | Custom search result component |
+| SearchAdvanced | React.ComponentType<SearchAdvancedProps> | DefaultSearchAdvanced | Custom advanced search component |
+| SearchResultsPresearch | React.ComponentType | - | Search placeholder component |
+| SearchResultsLoading | React.ComponentType | - | Loading placeholder component |
+| SearchResultsEmpty | React.ComponentType | - | Empty result placeholder component |
+| SearchResultItem | React.ComponentType<ResultItemProps> | - | Custom search result item component |
+| debounceTime | number | 300 | Search debounce time (ms) |
+| autoFocus | boolean | false | Auto-focus search box |
+| className | string | - | Custom style class name |
+| style | React.CSSProperties | - | custom style |
+| onKeywordChange | (keyword: string) => void | - | search keyword change callback |
+| onSearchComplete | (results: Map<SearchType, SearchResult>) => void | - | search complete callback |
+| onResultItemClick | (data: SearchResultItem, type: SearchType) => void | - | search result click callback |
+| onError | (error: Error) => void | - | search error callback |
+
+## Basic Usage
+``` typescript
+import { Search, VariantType } from '@tencentcloud/chat-uikit-react';
+
+function App() {
+  return (
+    <Search
+      variant={VariantType.STANDARD}
+      onResultItemClick={(data, type) => {
+        console.log('Search result click:', data, type);
+      }}
+    />
+  );
+}
+```
+
+## Custom Capabilities
+
+`Search` provides users with various and dimensional Props APIs, allowing them to customize features, UI, and modules.
+
+`Search` component provides multiple replaceable subcomponents, allowing users to customize `SearchBar`, `SearchResults`, `SearchAdvanced`, `SearchResultItem`, `SearchResultsPresearch`, `SearchResultsLoading`, `SearchResultsEmpty`. Users can also leverage default subcomponents for secondary development customization.
+
+【Custom SearchBar】
+
+**Props**
+| Attribute Name | Type | Default Value | Description |
+| --- | --- | --- | --- |
+| data | SearchResultItem | - | search result data |
+| type | SearchType | - | search result type |
+| keyword | string | - | search keyword |
+| onClick | (data: SearchResultItem, type: SearchType) => void | - | click callback |
+| className | string | - | Custom style class name |
+
+**Example**
+``` typescript
+const CustomSearchBar = ({ value, onChange, onClear, placeholder }) => (
+  <div className="custom-search-bar">
+    <input
+      type="text"
+      value={value}
+      onChange={onChange}
+      placeholder={placeholder}
+    />
+    {value && <button onClick={onClear}>Clear</button>}
+  </div>
+);
+
+<Search SearchBar={CustomSearchBar} />
+```
+
+【Custom Search Results】
+
+**Props**
+| Attribute Name | Type | Default Value | Description |
+| --- | --- | --- | --- |
+| results | `Map<SearchType, SearchResult>` | - | search result data |
+| isLoading | `boolean` | - | whether loading |
+| error | `Error \\| null` | - | Error Message |
+| keyword | `string` | - | search keyword |
+| typeLabels | `Record<SearchType, string>` | - | search type tag |
+| onLoadMore | `(type: SearchType) => void` | - | Load more callback |
+| onResultItemClick | `(data: SearchResultItem, type: SearchType) => void` | - | result item click callback |
+| SearchResultsLoading | `React.ComponentType` | `Loading` | Custom load component |
+| SearchResultsPresearch | `React.ComponentType` | - | Search placeholder component |
+| SearchResultsEmpty | `React.ComponentType` | `EmptyResult` | Empty result placeholder component |
+| SearchResultItem | `React.ComponentType<ResultItemProps>` | `DefaultSearchResultsItem` | Custom result item component |
+| variant | `VariantType` | `VariantType.STANDARD` | Display Mode |
+| searchType | `SearchType \\| 'all'` | `'all'` | Current search type |
+
+**Example**
+``` typescript
+const CustomSearchResults = ({ results, keyword, onResultItemClick }) => (
+  <div className="custom-results">
+    {Array.from(results.entries()).map(([type, result]) => (
+      <div key={type}>
+        <h3>{type}</h3>
+        {result.resultList.map((item, index) => (
+          <div key={index} onClick={() => onResultItemClick(item, type)}>
+            {/* Custom result item */}
+          </div>
+        ))}
+      </div>
+    ))}
+  </div>
+);
+
+<Search SearchResults={CustomSearchResults} />
+```
+
+【Custom Search Advanced】
+
+**Props**
+| Attribute Name | Type | Default Value | Description |
+| --- | --- | --- | --- |
+| variant | `VariantType` | - | Display Mode |
+| searchType | `SearchTabType` | - | Current search type |
+| advancedParams | `Map<SearchType, SearchParamsMap[SearchType]>` | - | Advanced search parameters |
+| onAdvancedParamsChange | `(type: SearchType, params: SearchParamsMap[SearchType]) => void` | - | Parameter change callback |
+
+**Example**
+``` typescript
+const CustomSearchAdvanced = ({ variant, searchType, advancedParams, onAdvancedParamsChange }) => (
+  <div className="custom-advanced">
+  {/* Custom advanced search function */}
+  </div>
+);
+
+<Search SearchAdvanced={CustomSearchAdvanced} />
+```
+
+【Custom Search Result Item】
+
+**Props**
+| Attribute Name | Type | Default Value | Description |
+| --- | --- | --- | --- |
+| data | `SearchResultItem` | - | search result data |
+| type | `SearchType` | - | search result type |
+| keyword | `string` | - | search keyword |
+| onClick | `(data: SearchResultItem, type: SearchType) => void` | - | click callback |
+| className | `string` | - | Custom style class name |
+
+**Example**
+``` typescript
+const CustomSearchItem = ({ data, type, keyword, onClick }) => (
+  <div className="custom-item">
+    {type === SearchType.MESSAGE && (
+        <Conversation
+          data={data}
+          keyword={keyword}
+          onClick={onClick}
+        />
+      )}
+      {type === SearchType.USER && (
+        <User
+          data={data}
+          keyword={keyword}
+          onClick={onClick}
+        />
+      )}
+      {type === SearchType.GROUP && (
+        <Group
+          data={data}
+          keyword={keyword}
+          onClick={onClick}
+        />
+      )}
+      {type === SearchType.CHAT_MESSAGE && (
+        <Message
+          data={data}
+          keyword={keyword}
+          onClick={onClick}
+        />
+      )}
+  </div>
+);
+
+<Search SearchResultItem={CustomSearchItem} />
+```
+
+【Custom Placeholder Component】
+
+**Props**
+| Attribute Name | Type | Default Value | Description |
+| --- | --- | --- | --- |
+| SearchResultsPresearch | `React.ComponentType` | - | Search placeholder component |
+| SearchResultsLoading | `React.ComponentType` | - | Loading placeholder component |
+| SearchResultsEmpty | `React.ComponentType` | - | Empty result placeholder component |
+
+**Example**
+``` typescript
+<Search
+  SearchResultsPresearch={() => <div>Enter keywords to start search</div>}
+  SearchResultsLoading={() => <div>Searching...</div>}
+  SearchResultsEmpty={() => <div>No result found</div>}
+/>
+```
+
+## FAQs
+
+### How to Customize the Search Result Display Format
+
+A: Use the `SearchResultItem` property to import a customize component.
+
+### How to Handle Search Performance Issues
+
+A: Adjust `debounceTime`, use React.memo, and consider result cache.
+
+### How to Optimize Mobile Terminal
+
+A: The component automatically adapts to mobile terminals and can be further customized via CSS.
+
+### How to Support Multilingual
+
+A: The component has built-in internationalization support. Use `useUIKit` to get translations.