@tencent-rtc/mcp 1.4.7 → 1.6.0

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

@@ -0,0 +1,261 @@
+TUIKit Flutter offers flexible appearance customization with support for Light, Dark, and System theme modes, along with customizable primary colors. A simple configuration enables theme switching and brand color application throughout your app.
+
+For example, in the message list, you can see how different theme modes and primary colors affect the UI:
+| <strong>Light + Default Color</strong> | <strong>Light + Orange</strong> | <strong>Dark + Default Color</strong> | <strong>Dark + Green Theme</strong> |
+| --- | --- | --- | --- |
+|  |  |  |  |
+
+## Core Features
+
+### Theme Mode
+- **Light Mode**: Provides a bright interface for daytime use.
+
+- **Dark Mode**: Displays a dim interface for low-light environments.
+
+- **System Mode**: Automatically matches the system's appearance setting.
+
+### Primary Theme Color Customization
+- **Preset Theme Colors**: Choose from built-in options like blue, green, red, orange, and more.
+
+- **Custom Theme Colors**: Set any Hex color value to match your brand.
+
+- **Smart Palette Generation**: Automatically creates a palette of 10 color shades based on your selected color.
+
+- **Reset to Default**: Easily revert to the default theme color with one click.
+
+## API Reference
+
+All theme configuration and queries are managed through the `ThemeState` API.
+
+### Setting Theme Mode
+| Method | Parameter | Return Value | Description |
+| --- | --- | --- | --- |
+| <code>setThemeMode</code> | <code>ThemeType</code> | <code>void</code> | Sets the theme mode, saves the setting, and refreshes the UI.<br>- <code>ThemeType.SYSTEM</code>: Follows system settings.<br>- <code>ThemeType.LIGHT</code>: Enables light mode.<br>- <code>ThemeType.DARK</code>: Enables dark mode. |
+
+### Setting Primary Theme Color
+
+|Method|Parameter|Return Value|Description|
+|---------|---------|---------|---------|
+|`setPrimaryColor`|`String`|`Unit`|Sets the primary theme color using a Hex string (e.g., "#1C66E5").|
+|`clearPrimaryColor`|None|`Unit`|Removes the custom theme color and resets to the default blue.|
+
+> **Notes****：**
+>
+> - Both `setThemeMode` and `setPrimaryColor` automatically persist the configuration. No manual save is required. Settings are restored on app startup.
+> - Changing theme configuration automatically clears the cache to ensure real-time updates. Manual cache management is not needed.
+> - Avoid calling theme APIs repeatedly (such as within loops).
+
+### Querying ThemeState
+
+Use the following read-only properties to retrieve the current theme configuration:
+
+|Property|Type|Description|
+|---------|---------|---------|
+|`currentMode`|`ThemeType`|The current theme mode.|
+|`currentPrimaryColor`|`String?`|The current primary theme color (Hex value).|
+|`hasCustomPrimaryColor`|`Boolean`|Indicates if a custom primary color is set.|
+|`isDarkMode`|`Boolean`|Indicates if dark mode is active.|
+
+## Usage
+
+This section covers how to integrate and apply theme and color customization in your app, with three recommended approaches ranging from basic to advanced.
+
+### Project Setup
+
+Wrap your app's entry point with `ComponentTheme` and configure `MaterialApp` as shown below. For implementation details, see the [demo](https://github.com/Tencent-RTC/TUIKit_Flutter/blob/main/chat/demo/lib/main.dart):
+``` java
+  @override
+  Widget build(BuildContext context) {
+    return ComponentTheme(
+      child: MultiProvider(
+        providers: [
+          ChangeNotifierProvider.value(value: LocaleProvider()),
+        ],
+        child: Builder(builder: (context) {
+          final themeState = BaseThemeProvider.of(context);
+          final isDarkMode = themeState.isDarkMode;
+          // ...... other configuration omitted
+          return MaterialApp(
+            themeMode: isDarkMode ? ThemeMode.dark : ThemeMode.light,
+            // ...... other configuration omitted
+          );
+        }),
+      ),
+    );
+```
+
+### Option A: Configure with AppBuilder (Recommended)
+
+AppBuilder is a flexible tool for customizing features and UI through a unified JSON configuration file. It is ideal for maintaining consistent appearance across Web and Native apps.
+
+Try AppBuilder in the [Chat Web Demo](https://trtc.io/demo/homepage/#/detail):
+
+While the Chat Web Demo does not currently preview mobile configuration in real time, mobile projects fully support AppBuilder configuration.
+
+Follow the steps below to apply your AppBuilder settings from the Web Demo to your mobile project:
+1. Download the configuration file.
+
+2. Add the appConfig.json file to your Flutter project.
+
+3. Load the configuration file on app startup.
+
+#### Step 1: Download the Configuration File
+
+Visit the [Chat Web Demo](https://trtc.io/demo/homepage/#/detail) and download the appConfig.json configuration file. The download path is:
+
+Below is an example of `appConfig.json`. Configuration items map directly to fields in AppBuilder. Appearance settings are located under the `theme` section:
+``` json
+{
+  "theme": {
+    "mode": "light", // Theme mode: "light" for Light Mode, "dark" for Dark Mode, "system" to follow device settings
+    "primaryColor": "#E65100" // Primary color in Hex format
+  },
+  "messageList": {
+    "alignment": "two-sided",
+    "enableReadReceipt": false,
+    "messageActionList": [
+        "copy",
+        "recall",
+        "quote",
+        "forward",
+        "delete"
+    ]
+  },
+  "conversationList": {
+    "enableCreateConversation": true,
+    "conversationActionList": [
+      "delete",
+      "mute",
+      "pin",
+      "markUnread"
+    ]
+  },
+  "messageInput": {
+    "hideSendButton": false,
+    "attachmentPickerMode": "collapsed"
+  },
+  "search": {
+    "hideSearch": false
+  },
+  "avatar": {
+    "shape": "circular"
+  }
+}
+```
+
+**Configuration Options**
+
+|Parameter|Type|Options|Description|
+|---------|---------|---------|---------|
+|`mode`|String|`"system"`, `"light"`, `"dark"`|Theme mode|
+|`primaryColor`|String|Hex value, e.g., `"#0ABF77"`|Primary theme color|
+
+#### Step 2: Add the Configuration File to Your Project
+
+Drag appConfig.json into your project. For example, in the [TUIKit Flutter](https://github.com/Tencent-RTC/TUIKit_Flutter/tree/main) demo, appConfig.json is placed in the assets folder:
+
+Declare the assets resource in your pubspec.yaml file:
+``` java
+assets:
+  - assets/
+```
+
+#### Step 3: Load the Configuration File
+
+Specify the JSON file path and load it during app initialization:
+``` java
+class _MyAppState extends State<MyApp> {
+  bool _isInitialized = false;
+
+  @override
+  void initState() {
+    super.initState();
+    _initializeApp();
+  }
+
+  Future<void> _initializeApp() async {
+    await StorageUtil.init();
+    await AppBuilder.init(configPath: 'packages/uikit_next/assets/appConfig.json');
+
+    if (mounted) {
+      setState(() {
+        _isInitialized = true;
+      });
+    }
+  }
+}
+```
+
+Once configured, TUIKit Flutter components will automatically use the theme mode and primary color defined in appConfig.json when the app starts.
+
+### Option B: Set Theme Mode in Code
+
+Set the theme mode directly using the `setThemeMode` API. Example:
+``` swift
+val themeState = ThemeState.shared
+Column {
+    Button(onClick = {
+        themeState.setThemeMode(ThemeMode.SYSTEM)
+    }) { Text(text = "Follow System") }
+    Button(onClick = {
+        themeState.setThemeMode(ThemeMode.LIGHT)
+    }) { Text(text = "Light Mode") }
+    Button(onClick = {
+        themeState.setThemeMode(ThemeMode.DARK)
+    }) { Text(text = "Dark Mode") }
+}
+```
+
+### Option C: Set Primary Color in Code
+
+Set the primary theme color using the `setPrimaryColor` API. Provide a Hex color value, and TUIKit Flutter will automatically generate a full palette for UI components. No manual color adaptation is required.
+``` swift
+final themeState = BaseThemeProvider.of(context);
+themeState.setPrimaryColor('#1C66E5');
+```
+
+> **Recommendations****：**
+>
+> - For most use cases, we recommend managing appearance via a JSON configuration file for simplicity, reliability, and cross-platform consistency.
+> - Always use colors from `themeState.colors` throughout your app to maintain a consistent look when switching themes.
+
+## FAQs
+
+### How do I check if dark mode is active?
+``` java
+if (themeState.isDarkMode) {
+  // Currently in dark mode
+} else {
+    // Currently in light mode
+}
+```
+
+### Can I set transparency for the theme color?
+
+No. Only 6-digit Hex codes (RGB) are supported; 8-digit Hex (RGBA) formats are not allowed.
+
+### How do I reset to the default theme?
+``` swift
+themeState.clearPrimaryColor()  // Removes custom theme color
+themeState.setThemeMode(ThemeType.SYSTEM)  // Switches to system default mode
+```
+
+### Where is theme configuration saved?
+
+Theme settings are stored in the app's persistent storage. If the app is uninstalled, the configuration is removed and reset to default on reinstall.
+
+### How do I retrieve the current theme configuration?
+``` swift
+final themeState = BaseThemeProvider.of(context);
+final config = themeState.currentTheme;
+print("Mode: ${config.type}");
+print("Primary color: ${config.primaryColor ?? "Default"}");
+```
+
+### Can I set both theme mode and primary color at the same time?
+
+Yes. You can call both methods independently, and the system will merge the settings automatically:
+``` swift
+themeState.setThemeMode(ThemeType.DARK)
+themeState.setPrimaryColor("#0ABF77")
+```

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

@@ -0,0 +1,94 @@
+## Component Overview
+
+ChatSetting is a set of chat settings components built with SwiftUI. It includes two main components: C2CChatSetting (C2C Chat Settings) and GroupChatSetting (Group Chat Settings).
+
+These components offer robust chat session management features, such as user information management, permission controls, group management, and other essential capabilities.
+| <strong>C2C Chat Settings Interface</strong> | <strong>Group Chat Settings Interface</strong> |
+| --- | --- |
+|  |  |
+
+## Component Integration
+
+ChatSetting is included in TUIKit SwiftUI. To use ChatSetting, integrate TUIKit SwiftUI into your project. For detailed integration steps, see the [TUIKit SwiftUI documentation](https://www.tencentcloud.com/document/product/1047/77460).
+
+## Component Structure
+
+ChatSetting contains two main components: C2CChatSetting (C2C Chat Settings) and GroupChatSetting (Group Chat Settings). Each provides a variety of configuration options.
+
+### C2C Chat Settings (C2CChatSetting)
+
+#### Initialization Parameters
+
+|Parameter Name|Type|Description|
+|---------|---------|---------|
+|`userID`|`String`|The user ID of the chat partner.|
+|`onSendMessageClick`|`(() -> Void)?`|The webhook triggered when the Send Message button is clicked (optional).|
+|`onContactDelete`|`(() -> Void)? `|The webhook triggered when the Delete Contact button is clicked (optional).|
+
+#### Initialization Interface
+
+|Method Name|Parameters|Description|
+|---------|---------|---------|
+|`init`|`userID: String, onSendMessageClick: (() -> Void)?, onContactDelete: (() -> Void)?`|Initializes the C2C Chat Settings component.|
+
+### Group Chat Settings (GroupChatSetting)
+
+#### Initialization Parameters
+
+|Parameter Name|Type|Description|
+|---------|---------|---------|
+|`groupID`|`String`|The group ID used to identify the group chat.|
+|`onSendMessageClick`|`(() -> Void)?`|Webhook triggered when the Send Message button is clicked (optional).|
+|`onGroupDelete`|`(() -> Void)?`|Webhook triggered when the Disband Group or Leave Group button is clicked (optional).|
+
+#### Initialization Interface
+
+|Method Name|Parameters|Description|
+|---------|---------|---------|
+|`init`|`groupID: String, onSendMessageClick: (() -> Void)?, onGroupDelete: (() -> Void)?`|Initializes the Group Chat Settings component.|
+
+## Basic Usage
+
+To display the C2C Chat Settings page, initialize C2CChatSetting as shown below:
+``` swift
+import AtomicX
+import SwiftUI
+
+struct C2CSettingView: View {
+    let userID: String
+
+    var body: some View {
+        C2CChatSetting(
+            userID: userID,
+            onSendMessageClick: {
+                // Handle send message button click
+            },
+            onContactDelete: {
+                // Handle delete contact button click
+            }
+        )
+    }
+}
+```
+
+To display the Group Chat Settings page, initialize GroupChatSetting as shown below:
+``` swift
+import AtomicX
+import SwiftUI
+
+struct GroupSettingView: View {
+    let groupID: String
+
+    var body: some View {
+        GroupChatSetting(
+            groupID: groupID,
+            onSendMessageClick: {
+                // Handle send message button click
+            },
+            onGroupDelete: {
+                // Handle disband or leave group button click
+            }
+        )
+    }
+}
+```

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

@@ -0,0 +1,119 @@
+## Component Overview
+
+ContactList is a SwiftUI component that provides a complete contact management interface. It supports displaying contacts, handling friend requests, managing group lists, blacklist management, and offers a variety of interactive webhook interfaces.
+| <strong>Contact List</strong> | <strong>Group List</strong> | <strong>Friend Request List</strong> |
+| --- | --- | --- |
+|  |  |  |
+
+## Component Integration
+
+The `ContactList` component is included in TUIKit SwiftUI. To use `ContactList`, integrate TUIKit SwiftUI into your project. For detailed integration steps, refer to the [TUIKit SwiftUI](https://www.tencentcloud.com/document/product/1047/77460) documentation.
+
+## Component Structure
+
+`ContactList` is the primary component for displaying and managing contacts. It represents the full contact list page and provides a public initializer:
+| <strong>Method</strong> | <strong>Parameter</strong> | <strong>Description</strong> |
+| --- | --- | --- |
+| <code>init</code> | <code>contactStore: ContactListStore</code> | Contact data store. Use <code>ContactListStore.create()</code> to create a default instance. |
+| <code>onContactClick: ((AZOrderedListItem) -> Void)?</code> | Webhook triggered when a contact is clicked. Optional. |  |
+| <code>onGroupClick: ((AZOrderedListItem) -> Void)?</code> | Webhook triggered when a group is clicked. Optional. |  |
+
+The top section of `ContactList` includes entry cells for subviews such as friend requests, group requests, group list, and blacklist. The lower section displays the contact list, as shown below:
+
+`ContactList` includes built-in navigation for subpages. When you tap entries such as friend requests, group requests, group list, or blacklist, the corresponding subpage opens automatically as a full-screen modal (fullScreenCover). No manual navigation handling is required.
+
+If you want to use subpages independently (such as the friend request list or group list), each subpage provides its own initializer, as described below:
+| <strong>Subpage</strong> | <strong>Method Name</strong> | <strong>Parameter</strong> | <strong>Description</strong> |
+| --- | --- | --- | --- |
+| Friend Request Page (FriendApplicationListView) | init | <code>contactStore: ContactListStore</code> | Contact data store, passed from ContactList |
+| init | <code>onDismiss: (() -> Void)?</code> | Webhook triggered when the page is closed. Optional. |  |
+| Group Request Page (GroupApplicationListView) | init | <code>contactStore: ContactListStore</code> | Contact data store, passed from ContactList |
+| init | <code>onDismiss: (() -> Void)?</code> | Webhook triggered when the page is closed. Optional. |  |
+| Group List Page (GroupListView) | init | <code>contactStore: ContactListStore</code> | Contact data store, passed from ContactList |
+| init | <code>onGroupClick: ((AZOrderedListItem) -> Void)?</code> | Webhook triggered when a group is clicked in the group list. Optional. |  |
+| init | <code>onDismiss: (() -> Void)?</code> | Webhook triggered when the page is closed. Optional. |  |
+| Blacklist Page (BlackListView) | init | <code>contactStore: ContactListStore</code> | Contact data store, passed from ContactList |
+| init | <code>onDismiss: (() -> Void)?</code> | Webhook triggered when the page is closed. Optional. |  |
+
+## Basic Usage
+
+### Quick Integration
+
+ContactList includes built-in navigation for all subpages. Simply initialize the component to enable full contact management features:
+``` swift
+import AtomicX
+import SwiftUI
+
+struct ContactsPage: View {
+    private let contactStore = ContactListStore.create()
+
+    var body: some View {
+        ContactList(
+            contactStore: contactStore,
+            onContactClick: { contact in
+                // Handle contact click
+                print("Contact clicked: \(contact.title)")
+            },
+            onGroupClick: { group in
+                // Handle group click (triggered when a group is clicked from the group list page)
+                print("Group clicked: \(group.title)")
+            }
+        )
+    }
+}
+```
+
+When you tap entries such as friend requests, group requests, group list, or blacklist, the component automatically opens the corresponding subpage as a full-screen modal. No additional navigation logic is required. See the navigation demo below:
+
+### Key Considerations
+
+#### Built-in Navigation
+
+ContactList automatically manages navigation for its subpages and presents them using fullScreenCover:
+- Friend Request Page (FriendApplicationListView)
+
+- Group Request Page (GroupApplicationListView)
+
+- Group List Page (GroupListView)
+
+- Blacklist Page (BlackListView)
+
+   You do not need to manage navigation state or configure NavigationLink manually.
+
+#### Webhook Handling
+
+ContactList provides two optional webhook callbacks:
+``` swift
+ContactList(
+    contactStore: contactStore,
+    onContactClick: { contact in
+        // Triggered when a contact in the contact list is clicked
+    },
+    onGroupClick: { group in
+        // Triggered when a group in the group list is clicked
+    }
+)
+```
+
+#### Data Sharing
+
+Create a data store instance using `ContactListStore.create()`. The component automatically shares this instance with all subpages to maintain data consistency:
+``` swift
+private let contactStore = ContactListStore.create()
+```
+
+#### Using Subpages Independently
+
+To use subpages independently in other parts of your app, initialize the corresponding view directly:
+``` swift
+// Use the group list page independently
+GroupListView(
+    contactStore: contactStore,
+    onGroupClick: { group in
+        print("Group clicked: \(group.title)")
+    },
+    onDismiss: {
+        // Close the page
+    }
+)
+```

package/resource/knowledge/chat/preset/ios/features/conversation-list.md

@@ -0,0 +1,134 @@
+## Component Overview
+
+ConversationList is a SwiftUI component for displaying and managing user chat conversations. It offers a full set of conversation list features, including conversation display and interactive actions.
+| <strong>Conversation List</strong> | <strong>Conversation Actions</strong> |
+| --- | --- |
+|  |  |
+
+## Component Integration
+
+ConversationList is part of TUIKit SwiftUI. To use ConversationList, integrate TUIKit SwiftUI into your project. For detailed integration steps, see the [TUIKit SwiftUI documentation](https://www.tencentcloud.com/document/product/1047/77460).
+
+## Component Structure
+
+ConversationList exposes only its initialization method. All other logic is encapsulated within the component.
+
+#### Public Methods
+| <strong>Method</strong> | <strong>Parameter</strong> | <strong>Description</strong> |
+| --- | --- | --- |
+| <code>init</code> | <code>onConversationClick: @escaping (ConversationInfo) -> Void</code> | Initializes the component and sets the conversation click Webhook. Required. |
+| <code>config: ConversationActionConfigProtocol = ChatConversationActionConfig()</code> | Initializes the component and sets the conversation action menu items. Optional. |  |
+| <code>customActions: [ConversationCustomAction] = []</code> | Initializes the component and sets custom conversation action options. Optional. |  |
+
+## Basic Usage
+
+You can initialize and use the ConversationList component directly. You must implement the onConversationClick Webhook.
+
+|**Parameter Name**|**Type**|**Description**|
+|---------|---------|---------|
+|`onConversationClick`|`(ConversationInfo) -> Void`|Conversation click Webhook, triggered when a user clicks a conversation cell.|
+
+Sample code:
+``` swift
+import AtomicX
+import SwiftUI
+
+struct ContentView: View {
+    var body: some View {
+        ConversationList(
+            onConversationClick: { conversation in
+                // Recommended: Navigate to the chat page here
+            }
+        )
+    }
+}
+```
+
+## Customization
+
+You can customize the action items in the conversation list using the following methods.
+
+#### Method 1. Hide Conversation Action Items Locally
+
+Pass a custom config when initializing ConversationList to control which menu items are displayed:
+``` swift
+struct CustomConversationView: View {
+    var body: some View {
+        ConversationList(
+            onConversationClick: { conversation in
+                // Navigate on conversation cell click
+            },
+            // Hide ClearHistory
+            config: ChatConversationActionConfig(isSupportDelete: true, isSupportPin: true, isSupportClearHistory: false)
+        )
+    }
+}
+```
+
+**Currently Supported Menu Item Toggles**
+
+|**Action Type**|**Description**|
+|---------|---------|
+|`isSupportDelete`|Enable or disable deleting conversations|
+|`isSupportPin`|Enable or disable Pin Conversation|
+|`isSupportClearHistory`|Enable or disable clearing conversation history|
+
+#### Method 2. Add Conversation Action Items Locally
+
+Pass `customActions` when initializing ConversationList. ConversationList will display your custom options below the default actions:
+
+|**Parameter Name**|**Type**|**Description**|
+|---------|---------|---------|
+|`customActions`|`[ConversationCustomAction]`|Custom conversation actions, shown when the user opens the conversation action menu.|
+
+Sample code:
+``` java
+struct CustomConversationView: View {
+    var body: some View {
+            ConversationList(
+                onConversationClick: { conversation in
+                    onShowMessage?(NavigationInfo(conversation: conversation))
+                },
+                // Custom actions
+                customActions: [
+                    ConversationCustomAction(title: "Share") { conversation in
+                        print("Share conversation: \(conversation.title ?? "")")
+                    },
+                ]
+            )
+            .conversationActions([.delete, .pin, .clearHistory])
+            .environmentObject(themeState)
+    }
+}
+
+```
+
+#### Method 3. Global Configuration
+
+Configure global action items using `AppBuilderConfig`:
+``` swift
+// Set this at application startup; if omitted, the feature is not enabled
+AppBuilderConfig.shared.conversationActionList = [
+    .delete,        // Enable delete
+    .pin,           // Enable Pin Conversation
+    .clearHistory   // Enable clearing conversation messages
+]
+
+// Then initialize ConversationList; all ConversationList instances will use the above conversationActionList configuration
+ConversationList(
+    onConversationClick: { conversation in
+        // Navigate to the chat page here if needed
+    }
+)
+```
+
+> **Note:**
+>
+
+> Local configuration takes precedence over global configuration.
+>
+
+The following images show the customization effects:
+| <strong>Conversation Actions</strong><br><strong> (Default Options)</strong> | <strong>Conversation Actions</strong><br><strong> (Delete Option Hidden)</strong> | <strong>Conversation Actions </strong><br><strong>(Share Option Added)</strong> |
+| --- | --- | --- |
+|  |  |  |