@tencent-rtc/mcp 1.4.7 → 1.6.0

package/resource/knowledge/chat/preset/react/features/message-list.md

@@ -0,0 +1,297 @@
+## Component Overview
+
+MessageList is a robust message list component for chat applications, offering flexible message display, rich interaction, and extensive customization. It supports core chat functionality including message aggregation, message read receipts, configurable message actions, scroll management, and advanced customization, making it suitable for a wide range of business scenarios.
+
+## Props
+| Field | Type | Default | Description |
+| --- | --- | --- | --- |
+| alignment | 'left' \\|'right' \\|'two-sided' | 'two-sided' | Sets message alignment mode.<br>- left: All messages are left-aligned.<br>- right: All messages are right-aligned.<br>- two-sided: Sent messages are right-aligned, received messages are left-aligned. |
+| enableReadReceipt | boolean | false | Enables the message read receipt feature. |
+| messageActionList | IMessageAction[] | ['copy', 'recall', 'quote', 'forward', 'delete'] | Customizes the list of message actions (e.g., copy, recall, delete, etc.). |
+| messageAggregationTime | number | 300 | Sets the message aggregation interval (seconds). Consecutive messages from the same sender within this interval are grouped together. |
+| filter | (message: MessageInfo) => boolean | undefined | Message filter function to control which messages are shown. |
+| className | string | undefined | Custom CSS class for the root container. |
+| style | React.CSSProperties | undefined | Custom inline styles for the root container. |
+| Message | React.ComponentType | Message | Custom message component renderer. |
+| MessageTimeDivider | React.ComponentType | MessageTimeDivider | Custom time divider component between messages. |
+
+## Detailed Props
+
+### alignment
+
+Type: `'left' | 'right' | 'two-sided'`
+
+The `alignment` prop determines how messages are aligned:
+- `two-sided`: Messages sent by others are left-aligned; messages sent by you are right-aligned (default).
+
+- `left`: All messages are left-aligned.
+
+- `right`: All messages are right-aligned.
+
+### enableReadReceipt
+
+Type: `boolean`
+
+Enables or disables message read receipts for each message. Default is `false`.
+
+### messageActionList
+
+Type: `IMessageAction[]`
+
+Customizes the available message actions (such as copy, recall, delete, etc.). By default, all actions are enabled: `['copy', 'recall', 'quote', 'forward', 'delete']`.
+``` tsx
+interface IMessageAction {
+  key: 'copy' | 'recall' | 'quote' | 'forward' | 'delete' | string;
+  label?: string;
+  icon?: React.ReactNode;
+  onClick?: (message: MessageInfo) => void;
+  visible?: ((message: MessageInfo) => boolean) | boolean;
+  component?: React.ComponentType<{ message: MessageInfo }>;
+  style?: React.CSSProperties;
+}
+```
+
+Use `useMessageActions` to retrieve and customize the full set of message actions.
+
+#### Example 1: Reorder message actions
+
+To display actions 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 (
+    <Chat>
+      <MessageList messageActionList={actions} />
+    </Chat>
+  );
+}
+```
+
+#### Example 2: Show only selected message actions
+
+To display only `forward`, `copy`, and `recall`:
+``` tsx
+import { Chat, MessageList, useMessageActions } from '@tencentcloud/chat-uikit-react';
+
+const App = () => {
+  const actions = useMessageActions(['forward', 'copy', 'recall']);
+  return (
+    <Chat>
+      <MessageList messageActionList={actions} />
+    </Chat>
+  );
+}
+```
+
+#### Example 3: Customize a message action
+
+For example, to modify the recall action:
+1. Set the label to 'Recall ⚠️'
+
+2. Change color to orange
+
+3. Only allow recall for text messages
+
+4. Use the original key `recall`
+
+   ``` tsx
+   import { Chat, MessageList, useMessageActions, MessageType } from '@tencentcloud/chat-uikit-react';
+
+   const ChatApp = () => {
+     const actions = useMessageActions(['copy', {
+       key: 'recall',
+       label: 'Recall ⚠️',
+       style: {
+         color: 'orange'
+       },
+       visible: (message) => message.messageType === MessageType.Text,
+     }, 'quote', 'forward', 'delete']);
+
+     return (
+       <Chat>
+         <MessageList messageActionList={actions} />
+       </Chat>
+     );
+   }
+   ```
+
+   Result:
+
+#### Example 4: Add a custom message action
+
+To add a custom action, such as 'Like', only for messages sent by others, and insert after 'recall':
+``` tsx
+import { useMessageAction } from '@tencentcloud/chat-uikit-react';
+import { yourApi } from '@/api/yourApi';
+
+const customActions = {
+  key: 'like',
+  label: 'Like',
+  icon: <span>👍</span>,
+  style: {
+    color: '#E53888',
+  },
+  visible: (message) => message.isSentBySelf === false,
+  onClick: (message) => {
+    yourApi.likeMessage(message.msgID);
+  }
+}
+
+function ChatApp() {
+  const actions = useMessageAction(['forward', 'copy', 'recall', customActions, 'quote', 'delete']);
+  return <MessageList messageActionList={actions} />;
+}
+```
+
+Result:
+
+### messageAggregationTime
+
+Type: `number`
+
+Defines the time interval for aggregating messages from the same sender. Messages sent within this interval are grouped together. Default value: `300` seconds.
+
+### filter
+
+Type: `(message: MessageInfo) => boolean`
+
+Provides a filter function to control which messages are displayed. Default is `undefined`.
+
+#### Example: Filtering bot error messages
+``` tsx
+import { MessageList, MessageType } from '@tencentcloud/chat-uikit-react';
+
+const messageFilter = (message) => {
+  // Hide text messages sent by users whose nickname contains '_robot' and content contains 'operation-failed'
+  if (
+    message.from.nickname?.includes('_robot')
+    && message.messageType === MessageType.Text
+    && message.messagePayload?.text?.includes('operation-failed')
+  ) {
+    return false;
+  }
+  return true;
+};
+
+function ChatApp() {
+  return <MessageList filter={messageFilter} />;
+}
+```
+
+### className
+
+Type: `string`
+
+Sets a custom CSS class name for the root container. Default is `undefined`.
+
+### style
+
+Type: `React.CSSProperties`
+
+Applies custom inline styles to the root container. Default is `undefined`.
+
+### Message
+
+Type: `React.ComponentType`
+
+Provides a custom message component, replacing the default renderer. Default is the built-in `Message` component.
+
+#### Example: Custom component for messages with link navigation
+``` tsx
+import { Chat, MessageList, Message, MessageType } from '@tencentcloud/chat-uikit-react';
+
+function CustomMessage(props) {
+  const { message } = props;
+
+  if (message.messageType === MessageType.Custom) {
+    const { businessID, ...restData } = JSON.parse(message.messagePayload.data);
+    if (businessID === 'text_link') {
+      return (
+        <div>
+          <div>{restData.text}</div>
+          <a href={restData.link}>
+            Go to external site {restData.link}
+          </a>
+        </div>
+      );
+    }
+  } else {
+    // Use default message component for other message types
+    return <Message {...props} />;
+  }
+}
+
+function ChatApp() {
+  return (
+    <Chat>
+      <MessageList Message={CustomMessage} />
+    </Chat>
+  );
+}
+```
+
+### MessageTimeDivider
+
+Type: `React.ComponentType`
+
+Lets you specify a custom component to display time dividers between messages. Default is the built-in `MessageTimeDivider`.
+
+#### Example: Time divider indicating working hours
+``` tsx
+import { Chat, MessageList, type MessageInfo } from '@tencentcloud/chat-uikit-react';
+
+const BusinessTimeDivider = ({ prevMessage, currentMessage }: { prevMessage: MessageInfo, currentMessage: MessageInfo }) => {
+  if (!prevMessage || !currentMessage) return null;
+
+  // For each message, compare timestamps to determine if a divider is needed
+  const currentTime = currentMessage.timestamp ?? new Date();
+  const prevTime = prevMessage.timestamp ?? new Date();
+
+  // Show divider if it's a new day or more than 4 hours apart
+  const shouldShow = currentTime.toDateString() !== prevTime.toDateString() ||
+                    (currentTime.getTime() - prevTime.getTime()) > 4 * 60 * 60 * 1000;
+
+  if (!shouldShow) return null;
+
+  // Check for working hours (9:00-18:00, Monday to Friday)
+  const isWorkingTime = () => {
+    const hour = currentTime.getHours();
+    const day = currentTime.getDay();
+    return day >= 1 && day <= 5 && hour >= 9 && hour <= 18;
+  };
+
+  const timeLabel = isWorkingTime() ? 'Working Hours' : 'Off Hours';
+  const timeColor = isWorkingTime() ? '#52c41a' : '#faad14';
+
+  return (
+    <div style={{ textAlign: 'center', margin: '16px 0' }}>
+      <span style={{
+        backgroundColor: timeColor,
+        color: 'white',
+        padding: '2px 8px',
+        borderRadius: '12px',
+        marginRight: '8px'
+      }}>
+        {timeLabel}
+      </span>
+      {currentTime.toLocaleString()}
+    </div>
+  );
+};
+
+function ChatApp() {
+  return (
+    <Chat>
+      <MessageList MessageTimeDivider={BusinessTimeDivider} />
+    </Chat>
+  );
+}
+```
+
+The renderings are shown as follows:
+
+## Summary
+
+MessageList provides a comprehensive set of message list features and powerful customization options. By configuring props and custom components as needed, you can build chat interfaces tailored to your business requirements. Choose configuration options based on your use case for optimal results.

package/resource/{doc/chatkit/react/components → knowledge/chat/preset/react/features}/search.md

@@ -22,30 +22,31 @@ Search (main component)
 ```
 
 ## Search Mode
-| **Mini Mode** | **Standard Mode** | **Embedded Mode** |
+| <strong>Mini Mode</strong> | <strong>Standard Mode</strong> | <strong>Embedded Mode</strong> |
 | --- | --- | --- |
 | - 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 |
+
+|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
@@ -72,13 +73,14 @@ function App() {
 【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 |
+
+|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
@@ -100,21 +102,22 @@ const CustomSearchBar = ({ value, onChange, onClear, placeholder }) => (
 【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 |
+
+|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
@@ -139,12 +142,13 @@ const CustomSearchResults = ({ results, keyword, onResultItemClick }) => (
 【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 |
+
+|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
@@ -160,13 +164,14 @@ const CustomSearchAdvanced = ({ variant, searchType, advancedParams, onAdvancedP
 【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 |
+
+|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
@@ -209,11 +214,12 @@ const CustomSearchItem = ({ data, type, keyword, onClick }) => (
 【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 |
+
+|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

package/resource/knowledge/chat/preset/react/features/theme.md

@@ -0,0 +1,93 @@
+## Overview
+
+UIKit React component library provides a complete theme system, supporting light and dark theme switching. With simple configuration, it can provide consistent visual experience for your application.
+
+### Feature
+- Light and dark theme seamless switching
+
+- ⚡ Real-time theme update
+
+- 🔧 Simple and easy-to-use configuration
+
+## Quick Start
+
+### Basic Configuration
+
+Use `UIKitProvider` to wrap your application and set the theme option to `theme="light"`. Besides, it also supports the dark theme `theme="dark"`.
+``` typescript
+import React from 'react';
+import { UIKitProvider, ConversationList, MessageList, ChatHeader, MessageInput, Chat } from '@tencentcloud/chat-uikit-react';
+
+function App() {
+  return (
+    <UIKitProvider
+      theme="dark"
+      language="en-US"
+    >
+      <div style={{ display: 'flex', height: '100vh' }}>
+        <ConversationList style={{ minWidth: '30%' }} />
+        <Chat>
+          <ChatHeader />
+          <MessageList />
+          <MessageInput />
+        </Chat>
+      </div>
+    </UIKitProvider>
+  );
+}
+
+export default App;
+```
+
+### Viewing and Switching Theme in Components
+
+Use the `useUIKit` Hook to access theme and language features.
+
+> **Note:**
+>
+
+> Note: Since the theme feature is implemented using React Context, `useUIKit()` is unable to be called in the root component.
+>
+
+``` typescript
+import React from 'react';
+import { useUIKit } from '@tencentcloud/chat-uikit-react';
+
+function SubComponent() {
+  const { theme, setTheme } = useUIKit();
+
+  return (
+    <div>
+      <p>Current theme: {theme}</p>
+
+      <button onClick={() => setTheme('dark')}>
+        switch to dark theme
+      </button>
+      <button onClick={() => setTheme('light')}>
+        switch to light theme
+      </button>
+    </div>
+  );
+}
+
+function App() {
+  return (
+    <UIKitProvider
+      theme="dark"
+      language="zh-CN"
+    >
+      <div style={{ display: 'flex', height: '100vh' }}>
+        <ConversationList style={{ minWidth: '30%' }} />
+        <Chat>
+          <SubComponent />
+          <ChatHeader />
+          <MessageList />
+          <MessageInput />
+        </Chat>
+      </div>
+    </UIKitProvider>
+  );
+}
+
+export default App;
+```