@tencentcloud/chat-uikit-react 2.3.1 → 3.0.1

package/src/components/ChatHeader/ChatHeader.stories.tsx

@@ -0,0 +1,129 @@
+/* eslint-disable import/order */
+import type { Meta, StoryObj } from '@storybook/react';
+import { TUICallKit } from '@tencentcloud/call-uikit-react';
+import { ChatHeader } from './ChatHeader';
+import { Chat } from '../Chat';
+import { useChatHeaderState, useUIManagerState } from '../../states';
+import { useEffect } from 'react';
+import { Avatar } from '../Avatar';
+import { startCall } from '../../utils/call';
+
+const meta: Meta<typeof ChatHeader> = {
+  title: 'Components/Chat/ChatHeader',
+  component: ChatHeader,
+  args: {
+    title: 'Chat Header',
+    avatar: 'https://picsum.photos/50',
+    enableUserStatus: true,
+    className: undefined,
+    style: undefined,
+  },
+  argTypes: {
+    title: {
+      control: {
+        type: 'text',
+      },
+    },
+    avatar: {
+      control: {
+        type: 'text',
+      },
+    },
+    enableUserStatus: {
+      control: {
+        type: 'boolean',
+      },
+    },
+    chatHeaderActions: {
+      control: {
+        type: 'object',
+      },
+    },
+  },
+  decorators: [
+    (Story) => {
+      const { conversationList, switchConversation } = useUIManagerState();
+
+      useEffect(() => {
+        if (conversationList?.[0]) {
+          switchConversation(conversationList[0].conversationID);
+        }
+      }, []);
+
+      return (
+        <div style={{ width: '100%' }}>
+          <Story />
+        </div>
+      );
+    },
+  ],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof ChatHeader>;
+
+export const Default: Story = {
+  render: args => (
+    <div>
+      <Chat>
+        <TUICallKit style={{ position: 'fixed' }} />
+        <ChatHeader {...args} />
+      </Chat>
+    </div>
+  ),
+};
+
+export const CustomAvatar: Story = {
+  args: {
+    chatHeaderActions: ['chatSetting', 'audioCall', 'videoCall'],
+  },
+  render: (args) => {
+    // eslint-disable-next-line @typescript-eslint/no-shadow
+    function CustomAvatar() {
+      return <Avatar image="https://picsum.photos/50" shape="square" size={30} style={{ marginRight: '10px' }} />;
+    }
+    return (
+      <div>
+        <Chat>
+          <ChatHeader
+            title="Custom Avatar"
+            Avatar={CustomAvatar}
+            {...args}
+          />
+        </Chat>
+      </div>
+    );
+  },
+};
+
+export const CustomComplete: Story = {
+  render: () => {
+    const { conversation, title, avatar } = useChatHeaderState();
+
+    // 目前仅支持 C2C
+    const startVideoCall = () => {
+      startCall({
+        callType: 'C2C',
+        callMediaType: 2,
+        userIDList: [conversation?.userProfile?.userID || '1'],
+      });
+    };
+
+    return (
+      <div>
+        <TUICallKit style={{ position: 'fixed' }} />
+        <Chat>
+          <div style={{ display: 'flex', alignItems: 'center', padding: 10 }}>
+            <Avatar
+              image={avatar || 'https://picsum.photos/50'}
+              style={{ marginRight: '10px' }}
+            />
+            <span>{title || 'I am ChatHeader'}</span>
+            <button onClick={startVideoCall}>video call</button>
+          </div>
+        </Chat>
+      </div>
+    );
+  },
+};

package/src/components/ChatHeader/ChatHeader.tsx

@@ -1,50 +1,76 @@
-import React, { PropsWithChildren } from 'react';
-import { Conversation } from '@tencentcloud/chat';
-import { useTUIChatStateContext } from '../../context/ChatStateContext';
-import type { TUIChatHeaderDefaultProps } from './ChatHeaderDefault';
-import { ChatHeaderDefault } from './ChatHeaderDefault';
-
-import './styles/index.scss';
-import { useComponentContext } from '../../context';
-
-interface TUIChatHeaderProps {
-  title?: string;
-  TUIChatHeader?: React.ComponentType<TUIChatHeaderDefaultProps>;
-  conversation?: Conversation;
-  avatar?: React.ReactElement | string;
-  headerOpateIcon?: React.ReactElement | string;
-  enableCall?: boolean;
+import type React from 'react';
+import { useEffect } from 'react';
+import { TUIUserService } from '@tencentcloud/chat-uikit-engine';
+import { useMessageInputState } from 'tuikit-atomicx-react';
+import { useChatHeaderState } from '../../states';
+import ChatHeaderUI from './ChatHeaderUI';
+import type { AvatarProps } from 'tuikit-atomicx-react';
+
+interface ChatHeaderProps {
+  /** Custom title, if not provided, will use conversation info */
+  title?: string | undefined;
+  /** Custom avatar image URL */
+  avatar?: string | undefined;
+  /** Whether to show user status */
+  enableUserStatus?: boolean | undefined;
+  /** Whether to enable chat setting */
+  chatHeaderActions?: Array<'videoCall' | 'audioCall' | 'chatSetting' | 'search'> | undefined;
+  /** Custom avatar component */
+  Avatar?: React.ComponentType<AvatarProps> | undefined;
+  /** Additional class names */
+  className?: string | undefined;
+  /** Additional style */
+  style?: React.CSSProperties | undefined;
+  onSearchClick?: (() => void) | undefined;
 }
 
-function UnMemoizedTUIChatHeader<T extends TUIChatHeaderProps>(
-  props: PropsWithChildren<T>,
-): React.ReactElement {
+const ChatHeader = (props: ChatHeaderProps) => {
   const {
     title,
-    conversation: propsConversation,
-    TUIChatHeader: propTUIChatHeader,
     avatar,
-    headerOpateIcon,
-    enableCall,
+    enableUserStatus = false,
+    chatHeaderActions,
+    Avatar,
+    className,
+    style,
   } = props;
 
-  const { conversation: contextConversation } = useTUIChatStateContext('TUIChatHeader');
-  const { TUIChatHeader: ContextTUIChatHeader } = useComponentContext('TUIChatHeader');
+  const {
+    system,
+    conversation,
+    isGroup,
+    title: exceptedTitle,
+    avatar: exceptedAvatar,
+    userStatus,
+  } = useChatHeaderState();
+
+  const { isPeerTyping } = useMessageInputState();
 
-  const TUIChatHeaderUIComponent = propTUIChatHeader
-    || ContextTUIChatHeader || ChatHeaderDefault;
-  const conversation = propsConversation || contextConversation;
+  useEffect(() => {
+    TUIUserService.switchUserStatus({ displayOnlineStatus: enableUserStatus });
+  }, [enableUserStatus]);
 
   return (
-    <TUIChatHeaderUIComponent
-      title={title}
+    <ChatHeaderUI
+      isGroup={isGroup}
+      title={title || exceptedTitle || ''}
+      avatar={avatar || exceptedAvatar}
+      userStatus={userStatus}
       conversation={conversation}
-      avatar={avatar}
-      opateIcon={headerOpateIcon}
-      enableCall={enableCall}
+      isPeerTyping={isPeerTyping}
+      system={system}
+      enableUserStatus={enableUserStatus}
+      chatHeaderActions={chatHeaderActions}
+      Avatar={Avatar}
+      style={style}
+      className={className}
+      onSearchClick={props.onSearchClick}
     />
   );
-}
+};
+
+export {
+  ChatHeader,
+};
 
-export const ChatHeader = React.memo(UnMemoizedTUIChatHeader) as
-typeof UnMemoizedTUIChatHeader;
+export type { ChatHeaderProps };

package/src/components/ChatHeader/ChatHeader.zh-CN.mdx

@@ -0,0 +1,159 @@
+import { Meta, Story, Canvas, Source, ArgTypes, Markdown, Controls } from '@storybook/blocks';
+import * as ChatHeaderStories from './ChatHeader.stories';
+
+<Meta of={ChatHeaderStories} name="文档" />
+
+# ChatHeader 聊天头部组件
+
+ChatHeader 组件是 @tencentcloud/chat-uikit-react 的核心组件之一。它提供了聊天会话的头部界面，显示聊天标题、用户头像、在线状态等信息，同时也是音视频通话的入口。
+
+## 特性
+
+- 显示会话标题和头像
+- 展示用户在线状态
+- 提供音视频通话入口
+- 支持自定义操作
+- 响应式设计和可定制样式
+
+## 基础用法
+
+<Source
+  language="tsx"
+  dark
+  code={`
+import { UIKitProvider } from '@tencentcloud/base-uikit-component-react';
+import { Chat, ChatHeader, MessageList, MessageInput } from '@tencentcloud/chat-uikit-react';
+
+/**
+ * login logic
+ */
+
+function App() {
+  return (
+    <UIKitProvider theme="light" language="en-US">
+      <Chat>
+        <ChatHeader />
+        <MessageList />
+        <MessageInput />
+      </Chat>
+    </UIKitProvider>
+  );
+}
+  `}
+/>
+
+<Canvas of={ChatHeaderStories.Default} />
+
+## 组件属性
+
+<Markdown>
+{`
+| 属性 | 类型 | 默认值 | 描述 |
+|--------|------|--------|------|
+| title | string | undefined | 会话名称，如果未设置，则使用默认会话信息 |
+| avatar | string | undefined | 会话头像url |
+| enableUserStatus | boolean | true | 是否展示对端用户在线状态，只有 C2C 会话有效 |
+| chatHeaderActions | Array<'videoCall' \\| 'audioCall' \\| 'chatSetting'> | ['videoCall', 'audioCall', 'chatSetting'] | 用于对 ChatHeader 上的功能进行显示隐藏 |
+| Avatar | React.ComponentType<> | undefined | 可传入自定义头像函数 |
+| className | string | undefined | 自定义类名 |
+| style | React.CSSProperties | undefined | 内联样式对象 |
+`}
+</Markdown>
+
+## 定制化
+
+#### 示例1：自定义头像
+
+`Avatar` 属性支持传入 React 组件，下面的例子是使用已有的 `Avatar` 组件自定义头像。
+
+<Source
+  language="tsx"
+  dark
+  code={`
+import { Avatar } from '@tencentcloud/chat-uikit-react';
+
+function CustomAvatar(props: React.ComponentProps<typeof Avatar>) {
+  console.log('>>> CustomAvatar props', props);
+  return <Avatar className={props.image} image={props.image} size={40} shape="square" />;
+}
+
+<Chat>
+  <ChatHeader
+    Avatar={CustomAvatar}
+  />
+</Chat>
+  `}
+/>
+
+<Canvas of={ChatHeaderStories.CustomAvatar} />
+
+#### 示例2：变更 ChatHeaderAction 功能的显隐和顺序
+
+取消展示 `videoCall` 和 `audioCall` 功能按钮。
+
+<Source
+  language="tsx"
+  dark
+  code={`
+// 默认值：['videoCall', 'audioCall', 'chatSetting']
+
+// 仅展示 chatSetting 按钮
+<ChatHeader
+  chatHeaderActions={['chatSetting']}
+/>
+
+// 调整 chatHeaderActions 的顺序
+<ChatHeader
+  chatHeaderActions={['chatSetting', 'videoCall', 'audioCall']}
+/>
+  `}
+/>
+
+#### 示例3：完全自定义 ChatHeader
+
+<Canvas of={ChatHeaderStories.CustomComplete} />
+
+<Source
+  language="tsx"
+  dark
+  code={`
+import { useChatHeaderStore } from '@tencentcloud/chat-uikit-react';
+
+function CustomChatHeader() {
+  const { conversation, title, avatar } = useChatHeaderStore();
+
+  // 需要集成 CallKit
+  const startVideoCall = () => {
+    startCall({
+      callType: conversation.type, // 目前仅支持 C2C
+      callMediaType: 2,
+      userIDList: [conversation?.userProfile?.userID],
+    });
+  };
+
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', padding: 10 }}>
+      <Avatar
+        image={avatar || 'https://picsum.photos/50'}
+        style={{ marginRight: '10px' }}
+      />
+      <span>{title || 'I am ChatHeader'}</span>
+      <button onClick={startVideoCall}>video call</button>
+    </div>
+  );
+}
+
+<Chat>
+  <CustomChatHeader />
+  <MessageList />
+  <MessageInput />
+</Chat>
+  `}
+/>
+
+## 相关组件
+
+- [Chat（聊天）](?path=/docs/components-chat--docs)
+- [Avatar（头像）](?path=/docs/components-avatar--docs)
+- [MessageList（消息列表）](?path=/docs/components-messagelist--docs)
+- [MessageInput（消息输入）](?path=/docs/components-messageinput--docs)

package/src/components/ChatHeader/ChatHeaderActions/ChatHeaderActions.module.scss

@@ -0,0 +1,44 @@
+@use "@tencentcloud/uikit-base-component-react/dist/styles/theme/util" as *;
+
+.chat-header-actions {
+  flex: 0 0 auto;
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  margin-left: auto;
+  gap: 8px;
+
+  &__button {
+    @include theme() {
+      color: get(text-color-link);
+    }
+  }
+}
+
+.icon-button {
+  flex: 0 0 auto;
+  border: none;
+  padding: 4px;
+  margin: 0;
+  background: none;
+  // inline-flex: keeps button width snug while aligning icon & text
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 8px;
+  transition: background-color 0.2s ease;
+  cursor: pointer;
+
+  @include theme() {
+    color: get(text-color-link);
+    background-color: get(dropdown-color-default);
+
+    &:hover {
+      background-color: get(dropdown-color-hover);
+    }
+
+    &:active {
+      background-color: get(dropdown-color-active);
+    }
+  }
+}

package/src/components/ChatHeader/ChatHeaderActions/ChatHeaderActions.tsx

@@ -0,0 +1,105 @@
+import { useCallback, useMemo } from 'react';
+import { CallMediaType } from '@tencentcloud/call-uikit-react';
+import TUIChatEngine from '@tencentcloud/chat-uikit-engine';
+import TUICore, { TUIConstants } from '@tencentcloud/tui-core';
+import { useUIKit, IconSearch, IconVideoDefault, IconCall1, IconHorizontalMoreTwo } from '@tencentcloud/uikit-base-component-react';
+import { useUIOpenControlState, View, useConversationListState, startCall } from 'tuikit-atomicx-react';
+import cs from 'classnames';
+import classes from './ChatHeaderActions.module.scss';
+
+interface IChatHeaderActionsProps {
+  /** Whether to enable call features */
+  chatHeaderActions?: Array<'videoCall' | 'audioCall' | 'chatSetting' | 'search'> | undefined;
+  /** Additional class names */
+  className?: string | undefined;
+  /** Additional style */
+  style?: React.CSSProperties | undefined;
+}
+
+const ChatHeaderActions = (props: IChatHeaderActionsProps) => {
+  const {
+    chatHeaderActions = ['videoCall', 'audioCall', 'search', 'chatSetting'],
+    className,
+    style,
+  } = props;
+
+  const { searchConfig } = useUIKit();
+
+  const { toggleChatSetting, toggleChatSearch } = useUIOpenControlState();
+  const { activeConversation } = useConversationListState();
+
+  // Check if call feature is available
+  // Check if TUICallKit service is available
+  const isSupportCall: boolean = useMemo<boolean>(() => !!TUICore.getService(TUIConstants.TUICalling.SERVICE.NAME), []);
+  const isGroup: boolean = activeConversation?.type === TUIChatEngine.TYPES.CONV_GROUP;
+
+  // Handle call button click
+  const startCalling = useCallback((callMediaType: CallMediaType) => {
+    // Check if call is supported
+    if (!isSupportCall) {
+      return;
+    }
+
+    // Check if user is available
+    if (!activeConversation?.userProfile?.userID) {
+      throw new Error('User ID is not available in Call.');
+    }
+
+    startCall({
+      callType: activeConversation.type,
+      callMediaType,
+      userIDList: [activeConversation.userProfile.userID],
+    });
+  }, [activeConversation, isSupportCall]);
+
+  const actionButtons = useMemo(() => {
+    const buttonConfig = {
+      videoCall: {
+        icon: <IconVideoDefault size="28px" />,
+        onClick: () => startCalling(CallMediaType.VIDEO),
+        show: isSupportCall && !isGroup,
+      },
+      audioCall: {
+        icon: <IconCall1 size="28px" />,
+        onClick: () => startCalling(CallMediaType.AUDIO),
+        show: isSupportCall && !isGroup,
+      },
+      search: {
+        icon: <IconSearch size="28px" />,
+        onClick: toggleChatSearch,
+        show: !searchConfig?.hideSearch,
+      },
+      chatSetting: {
+        icon: <IconHorizontalMoreTwo size="28px" />,
+        onClick: toggleChatSetting,
+        show: true,
+      },
+    };
+
+    return chatHeaderActions
+      .filter(action => !!buttonConfig[action]?.show)
+      .map((action) => {
+        const config = buttonConfig[action];
+        return (
+          <button
+            key={action}
+            className={cs(classes['icon-button'])}
+            onClick={config.onClick}
+          >
+            {config.icon}
+          </button>
+        );
+      });
+  }, [chatHeaderActions, isSupportCall, startCalling, isGroup, toggleChatSetting]);
+
+  return (
+    <View
+      className={cs(classes['chat-header-actions'], className)}
+      style={style}
+    >
+      {actionButtons}
+    </View>
+  );
+};
+export { ChatHeaderActions };
+export type { IChatHeaderActionsProps };

package/src/components/ChatHeader/ChatHeaderActions/index.ts

@@ -0,0 +1 @@
+export * from './ChatHeaderActions';

package/src/components/ChatHeader/ChatHeaderUI/ChatHeaderUI.module.scss

@@ -0,0 +1,111 @@
+@use "@tencentcloud/uikit-base-component-react/dist/styles/theme/util" as *;
+
+.chat-header {
+  padding: 14px 10px;
+  height: 64px;
+  display: flex;
+  justify-content: center;
+
+  @include responsive((
+    "mobile": (
+      padding: 14px 10px,
+    ),
+    "desktop": (
+      padding: 14px 20px,
+    ),
+  ));
+
+  @include theme() {
+    background-color: get(bg-color-operate);
+  }
+
+  &__container {
+    flex-direction: row;
+    align-items: center;
+    justify-content: space-between;
+  }
+
+  &__left {
+    flex: 1 1 auto;
+    display: flex;
+    flex-direction: row;
+    align-items: center;
+    gap: 12px;
+  }
+
+  &__back-icon {
+    @include responsive((
+      "mobile": (
+        display: flex,
+      ),
+      "desktop": (
+        display: none,
+      ),
+    ));
+  }
+
+  &__info {
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+  }
+
+  &__title {
+    display: block;
+    margin: 0;
+    font-size: 16px;
+    font-weight: bold;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+
+    @include theme() {
+      color: get(text-color-primary);
+    }
+  }
+
+  &__typing-indicator {
+    font-size: 12px;
+
+    @include theme() {
+      color: get(text-color-secondary);
+    }
+  }
+
+  &__live {
+    margin-top: 4px;
+    font-size: 12px;
+
+    @include theme() {
+      color: get(text-color-tertiary);
+    }
+  }
+}
+
+.icon-button {
+  flex: 0 0 auto;
+  border: none;
+  padding: 4px;
+  margin: 0;
+  background: none;
+  // inline-flex: keeps button width snug while aligning icon & text
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border-radius: 8px;
+  transition: background-color 0.2s ease;
+  cursor: pointer;
+
+  @include theme() {
+    color: get(text-color-link);
+    background-color: get(dropdown-color-default);
+
+    &:hover {
+      background-color: get(dropdown-color-hover);
+    }
+
+    &:active {
+      background-color: get(dropdown-color-active);
+    }
+  }
+}