@tencentcloud/chat-uikit-react 2.3.1 → 3.0.1

package/src/components/Chat/Chat.mdx

@@ -0,0 +1,271 @@
+import { Meta, Story, Canvas, Source, ArgTypes, Markdown } from '@storybook/blocks';
+import * as ChatStories from './Chat.stories';
+
+<Meta of={ChatStories} name="Documentation" />
+
+# Chat Component
+
+The Chat component is a container component and one of the core components of @tencentcloud/chat-uikit-react. It provides the main chat interface structure, serving as a wrapper for chat UI elements and managing the chat context.
+
+**The Chat component can be used independently.**
+
+## Features
+
+- Flexible layout structure
+- Customizable header, message list, and input components
+- Context provider for chat-related data
+- Responsive design with customizable style
+
+## Core Components
+
+The Chat component is usually used together with ChatHeader, MessageList, and MessageInput.
+
+- ChatHeader: Chat header component, used to display chat title, user avatar, user online status, etc. It is also the entry point for voice and video calls.
+- MessageList: Message list component, used to display chat messages.
+- MessageInput: Message input component, used to input chat messages.
+
+## Basic Usage
+
+The Chat component can be used independently. It requires a `defaultConversationID` parameter, and if provided, the Chat component will automatically switch to the corresponding conversation.
+
+<Source
+  language="tsx"
+  dark
+  code={`
+import React from 'react';
+import { TUILogin } from '@tencentcloud/tui-core';
+import { UIKitProvider } from '@tencentcloud/uikit-base-component-react';
+import { Chat, ChatHeader, MessageList, MessageInput } from '@tencentcloud/chat-uikit-react';
+
+const config = {
+  SDKAppID: 0, // Your SDKAppID, number type, Get it from Step 4
+  userID: 'YOUR_USER_ID', // Login UserID, string type,  Get it from Step 5
+  userSig: 'YOUR_USER_SIG', // Your userSig, string type,  Get it from Step 5
+}
+
+TUILogin.login({
+  ...config,
+  useUploadPlugin: true
+}).then(() => {
+}).catch(() => {});
+
+function MyChat() {
+  return (
+    <UIKitProvider language='en-US' theme='light'>
+      <Chat defaultConversationID="YOUR_CONVERSATION_ID">
+        <ChatHeader />
+        <MessageList />
+        <MessageInput />
+      </Chat>
+    </UIKitProvider>
+  );
+}
+`}
+/>
+
+## Property
+
+<Markdown>
+{`
+| Parameter | Type | Default | Description |
+| ------ | ------ | ------ | ------ |
+| defaultConversationID | string | \`undefined\` | Default conversation ID, if set, the component will automatically switch to the corresponding conversation |
+| ChatHeader | React.ComponentType | \`undefined\` | Custom chat header component to replace the default header |
+| MessageList | React.ComponentType | \`undefined\` | Custom message list component to replace the default list |
+| MessageInput | React.ComponentType | \`undefined\` | Custom message input component to replace the default input |
+| children | React.ReactNode | \`undefined\` | Child components, typically includes ChatHeader, MessageList, and MessageInput |
+| className | string | \`undefined\` | Custom class names for styling |
+| style | React.CSSProperties | \`undefined\` | Inline style object for custom styling |
+`}
+</Markdown>
+
+## Customization
+
+### Custom Styling
+
+You can customize the appearance of the Chat component using CSS modules or inline style:
+
+<Source
+  language="tsx"
+  dark
+  code={`
+import classes from './CustomChat.module.scss';
+
+<Chat
+  className={classes.customChat}
+  style={{
+    backgroundColor: '#f5f5f5',
+    padding: '20px',
+    borderRadius: '8px',
+    boxShadow: '0 2px 4px rgba(0, 0, 0, 0.1)'
+  }}
+>
+  <ChatHeader />
+  <MessageList />
+  <MessageInput />
+</Chat>
+`}
+/>
+
+### Custom Components
+
+You can provide custom components to replace the default ones:
+
+#### Custom Chat Header
+
+Use the `useChatHeaderProps` hook to get the chat header component props.
+
+<Source
+  language="tsx"
+  dark
+  code={`
+import { useChatHeaderProps } from '@tencentcloud/chat-uikit-react';
+
+const CustomChatHeader = () => {
+  const {
+    /** Chat avatar URL */
+    avatarUrl: string;
+    /** Chat title */
+    title: string | undefined;
+    /** User online status */
+    userStatus: IUserStatus | undefined;
+    /** Current conversation */
+    conversation: IConversationModel | undefined;
+    /** Is system conversation */
+    system: boolean | undefined;
+  } = useChatHeaderProps();
+
+  return (
+    <div className="custom-header">
+      <h1>{title}</h1>
+      <img src={avatarUrl} alt="avatar" />
+      {
+        userStatus?.statusType === 1
+        ? <div>Online</div>
+        : <div>Offline</div>
+      }
+    </div>
+  );
+};
+
+<Chat ChatHeader={CustomChatHeader}>
+  <ChatHeader />
+  <MessageList />
+  <MessageInput />
+</Chat>
+`}
+/>
+
+#### Custom Message List
+
+Use the `useChatContext` hook to get message list related data. Note that useChatContext is based on React Context and must be used within the Chat component.
+
+messageList will initially return the latest 15 messages by default. To get more messages, you can call the `getMessageList` method.
+
+You can use the `judgeHasMoreMessage` method to determine if there are more messages available.
+
+<Source
+  language="tsx"
+  dark
+  code={`
+import { useChatContext } from '@tencentcloud/chat-uikit-react';
+
+const CustomMessageList = () => {
+  const {
+    messageList,
+    getMessageList,
+    judgeHasMoreMessage,
+  } = useChatContext();
+
+  return (
+    <div className="custom-message-list">
+      {
+        judgeHasMoreMessage() && (
+          <div onClick={getMessageList}>Load More</div>
+        )
+      }
+      {messageList.map((message) => {
+        const diffKeyToFlush = \`\${message.ID}-\${message.isRevoked}-\${message.isDeleted}-\${message.status}\`;
+        return (
+          <div key={diffKeyToFlush}>
+            <div key={message.nick}>{message.nick}</div>
+            <img src={message.avatar} alt="avatar" />
+            {message.type === 'TIMTextElem' && <div>{message.payload.text}</div>}
+          </div>
+        );
+      })}
+    </div>
+  );
+};
+
+<Chat MessageList={CustomMessageList}>
+  <ChatHeader />
+  <MessageList />
+  <MessageInput />
+</Chat>
+`}
+/>
+
+#### Custom Message Input
+
+Use the `useMessageInputStore` hook to get message input related data.
+
+<Source
+  language="tsx"
+  dark
+  code={`
+import { useMessageInputStore } from '@tencentcloud/chat-uikit-react';
+
+const CustomMessageInput = () => {
+  const {
+    inputValue,
+    setInputValue,
+    sendTextMessage,
+  } = useMessageInputStore();
+
+  const handleSendMessage = () => {
+    sendTextMessage({
+      payload: {
+        text: inputValue,
+      },
+    });
+  };
+
+  return (
+    <div className="custom-message-list" style={{ padding: '16px', backgroundColor: '#fff' }}>
+      <input type="text" value={inputValue} onChange={e => setInputValue(e.target.value)} />
+      <button onClick={handleSendMessage}>Send</button>
+    </div>
+  );
+};
+
+<Chat
+  MessageInput={CustomMessageInput}
+>
+  <ChatHeader />
+  <MessageList />
+  <MessageInput />
+</Chat>
+`}
+/>
+
+## Best Practices
+
+1. **Context Usage**
+   - Use the Chat component at a high level in your component tree
+   - Ensure a valid conversation context before rendering
+
+2. **Component Customization**
+   - Custom components receive the same props as their default counterparts
+   - Use the provided hooks (`useChatHeaderProps`, `useChatContext`, `useMessageInputStore`) to access chat data
+
+3. **Styling**
+   - Use CSS modules for style isolation
+   - Apply custom style through `className` and `style` props
+   - Follow your application's design system
+
+## Related Components
+
+- [ChatHeader](?path=/docs/components-chat-chatheader--docs)
+- [MessageList](?path=/docs/components-chat-messagelist--docs)
+- [MessageInput](?path=/docs/components-chat-messageinput--docs)

package/src/components/Chat/Chat.module.scss

@@ -0,0 +1,11 @@
+.chat {
+  display: flex;
+  flex-direction: column;
+  height: 100%;
+  width: 100%;
+
+  &__container {
+    flex: 1;
+    overflow: hidden;
+  }
+}

package/src/components/Chat/Chat.stories.tsx

@@ -0,0 +1,215 @@
+/* eslint-disable import/order */
+import type { Meta, StoryObj } from '@storybook/react';
+import { useEffect } from 'react';
+import { Chat } from './Chat';
+import { ChatHeader } from '../../core/components/ChatHeader';
+import { MessageInput } from '../../core/components/MessageInput';
+import { MessageList } from '../../core/components/MessageList';
+import { Avatar } from '../Avatar';
+import { useMessageListStore, useUIManagerState } from '../../states';
+import { useChatHeaderStore } from '../../core/stores/useChatHeaderStore';
+import { ChatHeaderActions } from '../../core/components/ChatHeader/ChatHeaderActions';
+import { startCall } from '../../utils/call';
+import { TUICallKit } from '@tencentcloud/call-uikit-react';
+
+const meta: Meta<typeof Chat> = {
+  title: 'Components/Chat/Chat',
+  component: Chat,
+  argTypes: {
+    className: {
+      description: 'custom class names of root element',
+      control: 'text',
+      table: {
+        type: { summary: 'string | undefined' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    style: {
+      description: 'custom style of root element',
+      control: 'text',
+      table: {
+        type: { summary: 'React.CSSProperties | undefined' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+  },
+  parameters: {
+    layout: 'centered',
+    order: 1,
+  },
+  decorators: [
+    (Story) => {
+      const { conversationList, switchConversation } = useUIManagerState();
+
+      useEffect(() => {
+        if (conversationList?.[0]) {
+          switchConversation(conversationList[0].conversationID);
+        }
+      }, []);
+
+      return (
+        <div style={{ width: '100%', minHeight: '500px' }}>
+          <Story />
+        </div>
+      );
+    },
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <Chat>
+      <ChatHeader />
+      <MessageList />
+      <MessageInput />
+    </Chat>
+  ),
+};
+
+export const WithCustomHeaderButUseDefaultCallKit: Story = {
+  name: 'With Custom Header But Use Default <ChatHeaderActions />',
+  render: () => (
+    <Chat>
+      <div className="custom-header" style={{ padding: '16px', backgroundColor: '#f0f0f0', border: '1px solid #000' }}>
+        <section style={{ marginBottom: 16 }}>
+          <h1>Custom Header</h1>
+          <div>I am custom title</div>
+          <div>
+            Expected title:&nbsp;
+            Title
+          </div>
+        </section>
+        <section style={{ marginBottom: 16 }}>
+          <Avatar image="https://picsum.photos/200" size={24} />
+        </section>
+        <section>
+          <ChatHeaderActions chatHeaderActions={['chatSetting', 'audioCall', 'videoCall']} />
+        </section>
+      </div>
+      <MessageList style={{ height: 600 }} />
+      <MessageInput />
+    </Chat>
+  ),
+};
+
+export const WithCustomHeaderAndCustomActions: Story = {
+  name: 'With Custom Header And Custom <ChatHeaderActions />',
+  render: () => {
+    function CustomChatHeaderActions() {
+      const {
+        title,
+      } = useChatHeaderStore();
+      return (
+        <div className="custom-header" style={{ padding: '16px', backgroundColor: '#f0f0f0', border: '1px solid #000' }}>
+          <section style={{ marginBottom: 16 }}>
+            <h1>Custom Header</h1>
+            <div>I am custom title</div>
+            <div>
+              Expected title:&nbsp;
+              {title}
+            </div>
+          </section>
+          <section style={{ marginBottom: 16 }}>
+            <Avatar image="https://picsum.photos/200" size={24} />
+          </section>
+          <section>
+            <button onClick={() => {
+              startCall({
+                callMediaType: 1,
+                userIDList: ['RECEIVER_USER_ID'],
+                callType: 'C2C',
+              });
+            }}
+            >
+              audio call
+            </button>
+            <button onClick={() => {
+              startCall({
+                callMediaType: 2,
+                userIDList: ['RECEIVER_USER_ID'],
+                callType: 'C2C',
+              });
+            }}
+            >
+              video call
+            </button>
+          </section>
+        </div>
+      );
+    }
+
+    return (
+      <Chat>
+        <TUICallKit style={{ position: 'fixed' }} />
+        <CustomChatHeaderActions />
+        <MessageList />
+        <MessageInput />
+      </Chat>
+    );
+  },
+};
+
+export const WithCustomMessageList: Story = {
+  name: 'With Custom MessageList',
+  render: () => {
+    const {
+      messageList,
+    } = useMessageListStore();
+    return (
+      <Chat>
+        <ChatHeader />
+        <div className="custom-message-list" style={{ padding: '16px', backgroundColor: '#fff' }}>
+          {messageList.map((message) => {
+            const diffKeyToFlush = `${message.ID}-${message.isRevoked}-${message.isDeleted}-${message.status}`;
+            return (
+              <div key={diffKeyToFlush}>
+                <div key={message.nick}>{message.nick}</div>
+                <img src={message.avatar} alt="头像" />
+                {message.type === 'TIMTextElem' && <div>{message.payload.text}</div>}
+              </div>
+            );
+          })}
+        </div>
+        <MessageInput />
+      </Chat>
+    );
+  },
+};
+
+export const WithCustomMessageInput: Story = {
+  name: 'With Custom MessageInput',
+  render: () => (
+    <Chat>
+      <ChatHeader />
+      <MessageList />
+      <div className="custom-message-list" style={{ padding: '16px', backgroundColor: '#fff' }}>
+        <input type="text" />
+        <button>
+          发送
+        </button>
+      </div>
+    </Chat>
+  ),
+};
+
+export const WithCustomStyles: Story = {
+  args: {
+    className: 'custom-chat',
+    style: {
+      backgroundColor: '#f5f5f5',
+      padding: '20px',
+      borderRadius: '8px',
+      boxShadow: '0 2px 4px rgba(0, 0, 0, 0.1)',
+    },
+    children: (
+      <>
+        <ChatHeader />
+        <MessageList />
+        <MessageInput />
+      </>
+    ),
+  },
+};