@tencentcloud/chat-uikit-react 2.3.1 → 3.0.0

package/src/states/useChatHeaderStore.mdx

@@ -0,0 +1,182 @@
+import { Meta, Source, Markdown } from '@storybook/blocks';
+
+<Meta title="Hooks/Chat/useChatHeaderProps" />
+
+# useChatHeaderProps
+
+useChatHeaderProps 是一个用于获取 `ChatHeader` 信息的 Hook，可以用于自定义 `ChatHeader` 组件，它提供了当前会话的头像、标题、用户状态等信息。
+
+## Features
+
+- 获取当前会话的头像
+- 获取当前会话的标题
+- 获取当前会话的用户状态(仅在C2C中可用)
+- 获取当前选择的会话
+
+## Basic Usage
+
+<Source
+  language="tsx"
+  dark
+  code={`
+import { useChatHeaderProps } from '@tencentcloud/chat-uikit-react';
+
+function CustomChatHeader() {
+  const {
+    title,          // 会话标题
+    avatarUrl,      // 头像地址
+    userStatus,     // 用户在线状态
+    conversation,   // 当前会话对象
+    system,         // 是否为系统消息
+  } = useChatHeaderProps();
+
+  return (
+    <div>
+      <img src={avatarUrl} alt={title} />
+      <span>{title}</span>
+      {userStatus && <span>{userStatus.statusType}</span>}
+    </div>
+  );
+}
+  `}
+/>
+
+## Hook Return Values
+
+<Markdown>
+{`
+| 返回值 | 类型 | 默认值 | 描述 |
+|-------|------|---------|-------------|
+| avatarUrl | string | defaultUserAvatar/defaultGroupAvatarWork | 会话头像Url，单聊显示用户头像，群聊显示群头像 |
+| title | string \\| undefined | undefined | 会话标题，单聊显示用户昵称/备注，群聊显示群名称 |
+| userStatus | IUserStatus \\| undefined | undefined | 用户在线状态信息，仅在单聊中可用 |
+| conversation | IConversationModel \\| undefined | undefined | 当前会话的完整信息 |
+| system | boolean \\| undefined | undefined | 是否为系统消息会话，一般不需要关注 |
+`}
+</Markdown>
+
+<Source
+  language="tsx"
+  dark
+  code={`
+interface IUserStatus {
+  /**
+   * user status type
+   * 0: unknown
+   * 1: online
+   * 2: offline
+   * 3: unLogin
+   */
+  statusType: number;
+  /** custom status */
+  customStatus: string;
+}
+  `}
+/>
+
+## Example: 自定义ChatHeader
+
+<Source
+  language="tsx"
+  dark
+  code={`
+import { UIKitProvider } from '@tencentcloud/uikit-base-component-react';
+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>
+  );
+};
+
+export default function App() {
+  return (
+    <UIKitProvider theme={'light'} language={'en-US'}>
+      <Chat
+        defaultConversationID=""
+        ChatHeader={CustomChatHeader}
+      >
+        <ChatHeader />
+        <MessageList />
+        <MessageInput />
+      </Chat>
+    </UIKitProvider>
+  );
+}
+`}
+/>
+
+## Example: 群组信息展示
+
+<Source
+  language="tsx"
+  dark
+  code={`
+function GroupChatHeader() {
+  const {
+    conversation,
+    avatar,
+    title,
+  } = useChatHeaderProps();
+
+  const isGroup = conversation?.type === TUIChatEngine.TYPES.CONV_GROUP;
+
+  if (!isGroup) {
+    return null;
+  }
+
+  const { groupProfile } = conversation;
+
+  return (
+    <div className="group-header">
+      <img src={avatar} alt={title} />
+      <div className="group-info">
+        <div className="group-name">{title}</div>
+        <div className="group-member-count">
+          成员数: {groupProfile?.memberCount}
+        </div>
+      </div>
+    </div>
+  );
+}
+  `}
+/>
+
+## Best Practices
+
+1. **头像处理**
+   - 始终提供默认头像
+   - 处理头像加载失败的情况
+   - 根据会话类型显示不同的默认头像
+
+2. **标题���示**
+   - 优先显示备注名
+   - 其次显示昵称
+   - 最后使用 ID 作为标题
+   - 处理标题过长的情况
+
+3. **性能优化**
+   - 使用 useMemo 缓存计算结果
+   - 避免不必要的重渲染
+   - 按需订阅状态更新

package/src/stories/GettingStarted.mdx

@@ -0,0 +1,89 @@
+import { Meta } from '@storybook/blocks';
+
+<Meta title="Documentation/Getting Started" />
+
+# Getting Started
+
+@tencentcloud/chat-uikit-react is a chat UI component library based on React, providing a series of composable components to quickly build chat applications.
+
+
+## Install
+
+Using npm:
+
+```shell
+npm install @tencentcloud/chat-uikit-react @tencentcloud/uikit-base-components-react
+```
+
+## Basic Usage
+
+### 1. Quick Start
+
+The simplest way to use is to combine the `ConversationList` and `Chat` components:
+
+```tsx
+import React from 'react';
+import { TUILogin } from '@tencentcloud/tui-core';
+import { TUIConversationService } from '@tencentcloud/chat-uikit-engine';
+import { UIKitProvider } from '@tencentcloud/uikit-base-component-react';
+import { Profile, ConversationList, Chat, ChatHeader, MessageList, MessageInput, ChatSetting } 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(() => {
+  const defaultConversationID = '';
+  TUIConversationService.switchConversation(defaultConversationID);
+}).catch(() => {});
+
+export default function App() {
+  // language support en-US(default) / zh-CN / ja-JP / ko-KR / zh-TW
+  // theme support light(default) / dark
+  return (
+    <div style={{display: 'flex', height: '100vh'}}>
+      <UIKitProvider language='en-US' theme='light'>
+        <div style={{ display: 'flex', flexDirection: 'column', maxWidth: '30%' }}>
+          <Profile />
+          <ConversationList />
+        </div>
+        <Chat>
+          <ChatHeader />
+          <MessageList />
+          <MessageInput />
+        </Chat>
+        <ChatSetting />
+      </UIKitProvider>
+    </div>
+  );
+}
+```
+
+### 2. Create Application and Get SDKAppID/UserID/UserSig
+
+Read Doc [Create Application and Get SDKAppID/UserID/UserSig](https://cloud.tencent.com/document/product/269/4269).
+
+### 3. Run Project
+
+```shell
+npm start
+```
+
+## More Resources
+
+- [Github](https://github.com/TencentCloud/chat-uikit-react)
+- [Example code](https://github.com/TencentCloud/chat-uikit-react/tree/main/examples/sample-chat)
+- [@tencentcloud/uikit-base-component-react](https://www.npmjs.com/package/@tencentcloud/uikit-base-component-react)
+
+<style>
+  {`
+    h2 {
+      border: none !important;
+    }
+  `}
+</style>

package/src/styles/fonts/icon-font.scss

@@ -1,9 +1,9 @@
 @font-face {
   font-family: iconfont;
   src:
-    url("./assets/fonts/iconfont.woff2?t=1722856322648") format("woff2"),
-    url("./assets/fonts/iconfont.woff?t=1722856322648") format("woff"),
-    url("./assets/fonts/iconfont.ttf?t=1722856322648") format("truetype");
+    url("../../assets/fonts/iconfont.woff2") format("woff2"),
+    url("../../assets/fonts/iconfont.woff") format("woff"),
+    url("../../assets/fonts/iconfont.ttf") format("truetype");
 }
 
 .iconfont {

package/src/styles/index.scss

@@ -1,4 +1,2 @@
-@import "./normalize";
-@import "./fonts/icon-font";
-@import "./colors/color-light";
-@import "./colors/color-dark";
+@forward "./normalize";
+@forward "./fonts/icon-font";

package/src/styles/mixins/_scrollbar.scss

@@ -0,0 +1,62 @@
+@mixin scrollbar-base(
+  $width: 6px,
+  $height: 6px,
+  $border-radius: 4px,
+) {
+  overflow: auto;
+
+  &::-webkit-scrollbar {
+    width: $width;
+    height: $height;
+  }
+
+  &::-webkit-scrollbar-track {
+    background-color: transparent;
+  }
+
+  &::-webkit-scrollbar-thumb {
+    border-radius: $border-radius;
+    background-color: rgba(0, 0, 0, 12%);
+
+    &:hover {
+      background-color: rgba(0, 0, 0, 25%);
+    }
+  }
+
+  [data-uikit-theme="dark"] &::-webkit-scrollbar-thumb {
+    background-color: rgba(255, 255, 255, 14%);
+
+    &:hover {
+      background-color: rgba(255, 255, 255, 30%);
+    }
+  }
+}
+
+@mixin scrollbar-default {
+  @include scrollbar-base();
+}
+
+@mixin scrollbar-thin {
+  @include scrollbar-base(
+    $width: 4px,
+    $height: 4px,
+    $border-radius: 2px
+  );
+}
+
+@mixin scrollbar-hidden {
+  overflow: auto;
+  -ms-overflow-style: none; // IE and Edge
+  scrollbar-width: none; // Firefox
+
+  &::-webkit-scrollbar {
+    display: none; // Webkit browsers
+  }
+}
+
+// touch device enhance
+@mixin scrollbar-touch-friendly {
+  -webkit-overflow-scrolling: touch;
+
+  @include scrollbar-thin();
+}

package/src/styles/mixins/_text.scss

@@ -0,0 +1,25 @@
+@mixin text-ellipsis {
+  display: block;
+  overflow: hidden;
+  white-space: nowrap;
+  text-overflow: ellipsis;
+}
+
+/**
+  * Multi-line ellipsis
+  * @param {Number} $lines - The number of lines to show. Default is 2.
+  * @usage
+  * .class {
+  *   @include multi-line-ellipsis();
+  * }
+  * .class {
+  *   @include multi-line-ellipsis(3);
+  * }
+  */
+@mixin multi-line-ellipsis($lines: 2) {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  display: -webkit-box;
+  -webkit-line-clamp: $lines;
+  -webkit-box-orient: vertical;
+}

package/src/styles/mixins/index.scss

@@ -0,0 +1,2 @@
+@forward "./scrollbar";
+@forward "./text";

package/src/styles/normalize.scss

@@ -1,3 +1,5 @@
+/* stylelint-disable font-family-no-duplicate-names */
+
 /*! normalize.css v8.0.1 | MIT License | github.com/necolas/normalize.css */
 
 /* Document
@@ -62,7 +64,6 @@ hr {
  */
 
 pre {
-  /* stylelint-disable-next-line font-family-no-duplicate-names */
   font-family: monospace, monospace; /* 1 */
   font-size: 1em; /* 2 */
 }
@@ -354,8 +355,51 @@ template {
   -moz-osx-font-smoothing: grayscale;
 }
 
+/** custom normalize */
+
 *,
 *::after,
 *::before {
   box-sizing: border-box;
 }
+
+ul,
+li {
+  list-style: none;
+  padding: 0;
+  margin: 0;
+}
+
+// 响应式图片处理
+picture,
+img,
+video,
+canvas,
+svg {
+  display: block;
+  max-width: 100%;
+}
+
+/* stylelint-disable-next-line no-duplicate-selectors */
+img {
+  // 防止图片超出容器
+  max-width: 100%;
+  // 保持图片纵横比
+  height: auto;
+  // 消除图片底部间隙
+  vertical-align: middle;
+  // 让图片平滑缩放
+  image-rendering: -webkit-optimize-contrast;
+  // 在图片加载时保持布局稳定
+  aspect-ratio: attr(width) / attr(height);
+  // 设置默认显示模式
+  display: inline-block;
+  // 防止拖拽
+  -webkit-user-drag: none;
+  // 禁止用户选择
+  user-select: none;
+  // 图片加载失败时的降级处理
+  &:not([src], [srcset]) {
+    visibility: hidden;
+  }
+}

package/src/types/message.ts

@@ -0,0 +1,51 @@
+import type { IMessageModel } from '@tencentcloud/chat-uikit-engine';
+
+interface IScrollPosition {
+  /** The target scroll position from the top */
+  top: number;
+  /** The scroll behavior, defaults to 'smooth' */
+  behavior?: ScrollBehavior;
+}
+
+interface IReferenceContent {
+  messageAbstract: string;
+  messageID: string;
+  messageSender: string;
+  messageSequence: number;
+  messageTime: number;
+  messageType: number;
+  version: number;
+}
+
+interface ICloudCustomData {
+  messageReply: Partial<IReferenceContent>;
+}
+
+interface IMessageAction {
+  key: 'copy' | 'recall' | 'reference' | 'forward' | 'delete' | string;
+  label?: string;
+  icon?: React.ReactNode;
+  onClick?: (message: IMessageModel) => void;
+  visible?: ((message: IMessageModel) => boolean) | boolean;
+  component?: React.ComponentType<{ message: IMessageModel }>;
+  className?: string;
+  style?: React.CSSProperties;
+}
+
+type MessageAlignmentType = 'left' | 'right' | 'two-sided';
+
+interface IReadReceiptInfo {
+  readCount: number | undefined;
+  unreadCount: number | undefined;
+  isPeerRead: boolean | undefined;
+  timestamp: number;
+}
+
+export type {
+  IScrollPosition,
+  IReferenceContent,
+  ICloudCustomData,
+  IMessageAction,
+  MessageAlignmentType,
+  IReadReceiptInfo,
+};

package/src/types/user.ts

@@ -0,0 +1,20 @@
+interface IUserStatus {
+  /**
+   * user status type
+   * 0: unknown
+   * 1: online
+   * 2: offline
+   * 3: unLogin
+   */
+  statusType: number;
+  /**
+   * custom status
+   */
+  customStatus: string;
+}
+
+interface IUserStatusMap {
+  [userID: string]: IUserStatus;
+}
+
+export type { IUserStatus, IUserStatusMap };

package/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/tsconfig.app.json

@@ -0,0 +1,39 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
+    "target": "ES2020",
+    "useDefineForClassFields": true,
+    "lib": [
+      "ES2020",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    /* Bundler mode */
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+    /* Linting */
+    "strict": true,
+    "exactOptionalPropertyTypes": true,
+    "noUnusedLocals": false,
+    "noUnusedParameters": false,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true,
+    /* Plugins */
+    "plugins": [
+      {
+        "name": "typescript-plugin-css-modules"
+      }
+    ],
+  },
+  "include": [
+    "src",
+    ".storybook",
+    "playground"
+  ]
+}

package/tsconfig.json

@@ -1,16 +1,7 @@
 {
-  "compilerOptions": {
-    "target": "es5",
-    "esModuleInterop": true,
-    "allowSyntheticDefaultImports": true,
-    "exactOptionalPropertyTypes": false,
-    "moduleResolution": "node",
-    "jsx": "react-jsx",
-    "strict": true,
-    "lib": ["es6", "dom", "es2016"],
-  },
-  "include": [
-    "src"
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" }
   ]
 }
-

package/tsconfig.node.json

@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "target": "ES2022",
+    "lib": ["ES2023"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "Bundler",
+    "allowImportingTsExtensions": true,
+    "isolatedModules": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  },
+  "include": ["vite.config.ts", "vite.config.playground.ts"]
+}

package/vite.config.playground.ts

@@ -0,0 +1,48 @@
+// vite.config.playground.ts
+import react from '@vitejs/plugin-react';
+import postcssUrl from 'postcss-url';
+import { defineConfig } from 'vite';
+import { viteStaticCopy } from 'vite-plugin-static-copy';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    viteStaticCopy({
+      targets: [{
+        src: 'src/assets/fonts',
+        dest: 'assets',
+      }],
+    }),
+  ],
+  base: './',
+  build: {
+    outDir: 'dist-web', // 输出目录
+  },
+  server: {
+    host: '0.0.0.0',
+    port: 5173,
+  },
+  css: {
+    postcss: {
+      plugins: [
+        postcssUrl({
+          url: (asset) => {
+            if (!/\.(woff|woff2|ttf)$/.test(asset.pathname || '')) {
+              return asset.url;
+            }
+            // ensure paths are correct in npm publish
+            return `"../assets/fonts/${asset.url.split('/').pop()}"`;
+          },
+        }),
+      ],
+    },
+    preprocessorOptions: {
+      scss: {
+        api: 'modern-compiler',
+        additionalData: `
+          @use "@tencentcloud/uikit-base-component-react/dist/styles/theme/util" as *;
+        `,
+      },
+    },
+  },
+});