@anker-in/campaign-ui 0.2.11-beta.2 → 0.2.11-beta.21

package/src/components/LiveChatWidget/components/MessageList.tsx

@@ -0,0 +1,261 @@
+/**
+ * 消息列表组件
+ * 显示所有聊天消息，支持滚动
+ * 基于 specs/livechat-widget/plan.md 的消息列表设计
+ */
+
+import React, { useRef, useEffect, useState, useCallback } from 'react'
+import type { Message, MessageRenderer } from '../types'
+import { ChatMessage } from './ChatMessage'
+import { ScrollAnchor } from './ScrollAnchor'
+import { MessageRendererRegistry } from '../utils/messageRenderers'
+
+export interface MessageListProps {
+  /**
+   * 消息列表
+   */
+  messages: Message[]
+
+  /**
+   * 自定义渲染器注册表
+   */
+  rendererRegistry?: MessageRendererRegistry
+
+  /**
+   * 默认渲染器
+   */
+  defaultRenderer?: MessageRenderer
+
+  /**
+   * 是否显示时间戳
+   * @default true
+   */
+  showTimestamp?: boolean
+
+  /**
+   * 是否自动滚动到底部
+   * @default true
+   */
+  autoScroll?: boolean
+
+  /**
+   * 是否正在加载历史消息
+   * @default false
+   */
+  isLoadingHistory?: boolean
+
+  /**
+   * 空状态占位内容
+   */
+  emptyPlaceholder?: React.ReactNode
+
+  /**
+   * 自定义样式类名
+   */
+  className?: string
+
+  /**
+   * 商品添加到购物车回调
+   */
+  onAddToCart?: (product: any) => void
+}
+
+/**
+ * 默认空状态占位
+ */
+const DefaultEmptyPlaceholder: React.FC = () => (
+  <div className="flex h-full items-center justify-center text-gray-400">
+    <p className="text-sm">暂无消息</p>
+  </div>
+)
+
+/**
+ * 加载指示器
+ */
+const LoadingIndicator: React.FC = () => (
+  <div className="flex justify-center py-4">
+    <div className="flex gap-1">
+      <div className="size-2 animate-bounce rounded-full bg-gray-400" />
+      <div className="size-2 animate-bounce rounded-full bg-gray-400" style={{ animationDelay: '0.1s' }} />
+      <div className="size-2 animate-bounce rounded-full bg-gray-400" style={{ animationDelay: '0.2s' }} />
+    </div>
+  </div>
+)
+
+/**
+ * 消息列表组件
+ *
+ * 功能：
+ * - 显示所有消息（用户、助手、系统）
+ * - 自动滚动到最新消息
+ * - 加载历史消息时显示指示器
+ * - 空状态占位
+ *
+ * 样式：
+ * - 使用自定义滚动条样式（livechat.css）
+ * - 内容间距合理
+ * - 支持响应式布局
+ *
+ * @example
+ * ```tsx
+ * <MessageList
+ *   messages={messages}
+ *   rendererRegistry={customRegistry}
+ *   autoScroll={true}
+ *   isLoadingHistory={isLoading}
+ * />
+ * ```
+ */
+export const MessageList: React.FC<MessageListProps> = ({
+  messages,
+  rendererRegistry,
+  defaultRenderer,
+  showTimestamp = true,
+  autoScroll = true,
+  isLoadingHistory = false,
+  emptyPlaceholder,
+  className = '',
+  onAddToCart,
+}) => {
+  const listRef = useRef<HTMLDivElement>(null)
+  const [showScrollButton, setShowScrollButton] = useState(false)
+
+  // 检查是否接近底部
+  const isNearBottom = useCallback((threshold = 100) => {
+    const container = listRef.current
+    if (!container) return true
+
+    const { scrollTop, scrollHeight, clientHeight } = container
+    return scrollHeight - scrollTop - clientHeight < threshold
+  }, [])
+
+  // 平滑滚动到底部
+  const scrollToBottom = useCallback(() => {
+    const container = listRef.current
+    if (!container) return
+
+    container.scrollTo({
+      top: container.scrollHeight,
+      behavior: 'smooth',
+    })
+  }, [])
+
+  // 监听滚动事件，控制按钮显示
+  useEffect(() => {
+    const container = listRef.current
+    if (!container) return
+
+    const handleScroll = () => {
+      setShowScrollButton(!isNearBottom())
+    }
+
+    // 初始检查
+    handleScroll()
+
+    container.addEventListener('scroll', handleScroll, { passive: true })
+    return () => container.removeEventListener('scroll', handleScroll)
+  }, [isNearBottom])
+
+  // 当消息列表变化时，重新检查按钮状态（但不在自动滚动时）
+  useEffect(() => {
+    if (autoScroll) return // 自动滚动会在另一个 effect 中处理
+
+    const timeoutId = setTimeout(() => {
+      setShowScrollButton(!isNearBottom())
+    }, 150)
+
+    return () => clearTimeout(timeoutId)
+  }, [messages, autoScroll, isNearBottom])
+
+  // 监听消息列表变化，自动滚动
+  useEffect(() => {
+    if (!autoScroll || !listRef.current) return
+
+    // 延迟滚动以确保 DOM 已更新
+    const timeoutId = setTimeout(() => {
+      if (listRef.current) {
+        listRef.current.scrollTop = listRef.current.scrollHeight
+        // 自动滚动到底部后，隐藏按钮
+        setShowScrollButton(false)
+      }
+    }, 100)
+
+    return () => clearTimeout(timeoutId)
+  }, [messages, autoScroll])
+
+  // 空状态
+  if (messages.length === 0 && !isLoadingHistory) {
+    return (
+      <div className={`flex-1 overflow-hidden ${className}`}>{emptyPlaceholder || <DefaultEmptyPlaceholder />}</div>
+    )
+  }
+
+  return (
+    <div className="relative flex-1 overflow-hidden">
+      <div
+        ref={listRef}
+        className={`
+          livechat-message-list absolute inset-0 overflow-y-auto p-4
+          ${className}
+        `}
+      >
+        {/* 加载历史消息指示器 */}
+        {isLoadingHistory && <LoadingIndicator />}
+
+        {/* 消息列表 */}
+        <div className="flex flex-col gap-1">
+          {messages.map(message => (
+            <ChatMessage
+              key={message.id}
+              message={message}
+              rendererRegistry={rendererRegistry}
+              defaultRenderer={defaultRenderer}
+              showTimestamp={showTimestamp}
+              onAddToCart={onAddToCart}
+            />
+          ))}
+        </div>
+
+        {/* 滚动锚点 */}
+        {autoScroll && <ScrollAnchor dependencies={[messages]} />}
+      </div>
+
+      {/* 回到底部按钮 */}
+      <button
+        onClick={scrollToBottom}
+        className={`flex -translate-x-1/2 items-center justify-center ${showScrollButton ? '' : 'pointer-events-none'}`}
+        style={{
+          position: 'absolute',
+          bottom: '24px',
+          left: '50%',
+          zIndex: 10,
+          width: '40px',
+          height: '40px',
+          borderRadius: '50%',
+          backgroundColor: 'rgba(255, 255, 255, 0.95)',
+          boxShadow: '0 10px 15px -3px rgb(0 0 0 / 0.1), 0 4px 6px -4px rgb(0 0 0 / 0.1)',
+          transition: 'all 300ms ease-in-out',
+          opacity: showScrollButton ? 1 : 0,
+          cursor: 'pointer',
+          border: 'none',
+        }}
+        aria-label="Scroll to bottom"
+        aria-hidden={!showScrollButton}
+      >
+        <svg
+          width="20"
+          height="20"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          strokeWidth="2"
+          strokeLinecap="round"
+          strokeLinejoin="round"
+          className="text-gray-700"
+        >
+          <polyline points="6 9 12 15 18 9" />
+        </svg>
+      </button>
+    </div>
+  )
+}

package/src/components/LiveChatWidget/components/ScrollAnchor.tsx

@@ -0,0 +1,75 @@
+/**
+ * 滚动锚点组件
+ * 用于自动滚动到消息列表底部
+ * 基于 specs/livechat-widget/plan.md 的滚动行为设计
+ */
+
+import React, { useEffect, useRef } from 'react'
+
+export interface ScrollAnchorProps {
+  /**
+   * 是否自动滚动
+   * @default true
+   */
+  autoScroll?: boolean
+
+  /**
+   * 滚动行为
+   * @default "smooth"
+   */
+  behavior?: ScrollBehavior
+
+  /**
+   * 依赖项（当依赖项变化时触发滚动）
+   */
+  dependencies?: any[]
+}
+
+/**
+ * 滚动锚点组件
+ *
+ * 功能：
+ * - 放置在消息列表底部
+ * - 当新消息到达时自动滚动到此位置
+ * - 支持平滑滚动动画
+ *
+ * 使用场景：
+ * - 接收新消息时自动滚动
+ * - 发送消息后自动滚动
+ * - 加载历史消息后保持位置
+ *
+ * @example
+ * ```tsx
+ * <MessageList>
+ *   {messages.map(msg => <ChatMessage key={msg.id} message={msg} />)}
+ *   <ScrollAnchor dependencies={[messages]} />
+ * </MessageList>
+ * ```
+ */
+export const ScrollAnchor: React.FC<ScrollAnchorProps> = ({
+  autoScroll = true,
+  behavior = 'smooth',
+  dependencies = [],
+}) => {
+  const anchorRef = useRef<HTMLDivElement>(null)
+
+  useEffect(() => {
+    if (!autoScroll) return
+
+    const anchor = anchorRef.current
+    if (!anchor) return
+
+    // 使用 setTimeout 确保 DOM 已更新
+    const timeoutId = setTimeout(() => {
+      anchor.scrollIntoView({
+        behavior,
+        block: 'end',
+        inline: 'nearest',
+      })
+    }, 100)
+
+    return () => clearTimeout(timeoutId)
+  }, [autoScroll, behavior, ...dependencies])
+
+  return <div ref={anchorRef} style={{ height: 0 }} />
+}

package/src/components/LiveChatWidget/constants.ts

@@ -0,0 +1,15 @@
+/**
+ * LiveChat 组件常量定义
+ */
+
+/**
+ * 货币符号映射表
+ * 用于将货币代码转换为对应的符号
+ */
+export const CURRENCY_SYMBOLS: Record<string, string> = {
+  USD: '$',
+  EUR: '€',
+  GBP: '£',
+  JPY: '¥',
+  CNY: '¥',
+}

package/src/components/LiveChatWidget/hooks/useChatAPI.ts

@@ -0,0 +1,136 @@
+/**
+ * 聊天 API 调用 Hook
+ * 封装 SSE 流式消息接收、历史消息加载、新会话创建
+ * 基于 specs/livechat-widget/plan.md 的 API 调用策略
+ */
+
+import { useCallback, useRef } from 'react'
+import type { ChatStreamRequest, SSEEvent, NewSessionRequest, NewSessionResponse } from '../types'
+import { sendMessage, createNewSession } from '../api/chat'
+
+export interface UseChatAPIOptions {
+  /**
+   * API 基础 URL
+   */
+  apiBaseUrl: string
+
+  /**
+   * 错误处理回调
+   */
+  onError?: (error: Error) => void
+}
+
+export interface UseChatAPIReturn {
+  /**
+   * 发送消息并接收 SSE 流式响应
+   * @param request 请求参数
+   * @param onEvent SSE 事件回调
+   * @returns Promise<void>
+   */
+  sendMessageStream: (request: ChatStreamRequest, onEvent: (event: SSEEvent) => void) => Promise<void>
+
+  /**
+   * 创建新会话或恢复现有会话
+   * @param request 请求参数
+   * @returns 新会话信息，可能包含历史消息
+   */
+  createSession: (request: NewSessionRequest) => Promise<NewSessionResponse>
+
+  /**
+   * 中断当前的 SSE 流
+   */
+  abortStream: () => void
+
+  /**
+   * 是否正在发送消息
+   */
+  isSending: boolean
+}
+
+/**
+ * 聊天 API 调用 Hook
+ *
+ * 功能：
+ * 1. sendMessageStream: 发送消息并接收 SSE 流式响应
+ * 2. createSession: 创建新会话或恢复现有会话
+ * 3. abortStream: 中断当前流
+ *
+ * @param options Hook 配置选项
+ * @returns API 调用工具对象
+ */
+export function useChatAPI(options: UseChatAPIOptions): UseChatAPIReturn {
+  const { apiBaseUrl, onError } = options
+
+  // 用于中断当前请求的 AbortController
+  const abortControllerRef = useRef<AbortController | null>(null)
+
+  // 发送状态标记
+  const isSendingRef = useRef(false)
+
+  /**
+   * 发送消息并接收 SSE 流式响应
+   */
+  const sendMessageStream = useCallback(
+    async (request: ChatStreamRequest, onEvent: (event: SSEEvent) => void) => {
+      // 如果正在发送，先中断之前的请求
+      if (abortControllerRef.current) {
+        abortControllerRef.current.abort()
+      }
+
+      // 创建新的 AbortController
+      abortControllerRef.current = new AbortController()
+      isSendingRef.current = true
+
+      try {
+        await sendMessage(apiBaseUrl, request, onEvent)
+      } catch (error) {
+        // 忽略手动中断的错误
+        if (error instanceof Error && error.name === 'AbortError') {
+          return
+        }
+
+        console.error('[useChatAPI] Stream error:', error)
+        onError?.(error as Error)
+        throw error
+      } finally {
+        isSendingRef.current = false
+        abortControllerRef.current = null
+      }
+    },
+    [apiBaseUrl, onError]
+  )
+
+  /**
+   * 创建新会话或恢复现有会话
+   */
+  const createSession = useCallback(
+    async (request: NewSessionRequest): Promise<NewSessionResponse> => {
+      try {
+        return await createNewSession(apiBaseUrl, request)
+      } catch (error) {
+        console.error('[useChatAPI] Create session error:', error)
+        onError?.(error as Error)
+        throw error
+      }
+    },
+    [apiBaseUrl, onError]
+  )
+
+  /**
+   * 中断当前的 SSE 流
+   */
+  const abortStream = useCallback(() => {
+    if (abortControllerRef.current) {
+      abortControllerRef.current.abort()
+      abortControllerRef.current = null
+      isSendingRef.current = false
+    }
+  }, [])
+
+  return {
+    sendMessageStream,
+    createSession,
+    abortStream,
+    isSending: isSendingRef.current,
+  }
+}