@anker-in/campaign-ui 0.3.2 → 0.3.4

package/src/components/LiveChatWidget/components/MessageContent/ThinkingBlock.tsx

@@ -0,0 +1,53 @@
+/**
+ * 思考状态消息渲染器
+ * 显示 AI 助手正在思考的动画
+ * 基于 specs/livechat-widget/plan.md 的思考状态设计
+ */
+
+import React from 'react'
+import type { MessageRenderer, ThinkingContent } from '../../types'
+
+/**
+ * 思考状态渲染器
+ *
+ * 功能：
+ * - 显示"正在思考..."动画
+ * - 三个跳动的圆点
+ * - 黄色背景提示
+ *
+ * 动画效果：
+ * - 使用 CSS 动画（livechat.css 中定义）
+ * - 三个圆点依次跳动
+ * - 循环播放
+ *
+ * @example
+ * ```tsx
+ * const content: ThinkingContent = {
+ *   type: 'thinking',
+ *   data: {
+ *     status: '正在查询商品信息...'
+ *   }
+ * }
+ * <ThinkingBlock.render(content, false, false) />
+ * ```
+ */
+export const ThinkingBlock: MessageRenderer = {
+  render: (content, isUser, isSystem) => {
+    const thinkingContent = content as ThinkingContent
+    const status = thinkingContent.data.status || ''
+
+    return (
+      <div className="flex items-center gap-2 py-1">
+        {/* 思考动画 - 三个跳动的点 */}
+        <div className="livechat-thinking-dots flex gap-1">
+          <span className="size-2 rounded-full" style={{ backgroundColor: 'rgba(0, 93, 142, 1)' }} />
+          <span className="size-2 rounded-full" style={{ backgroundColor: 'rgba(0, 93, 142, 0.6)' }} />
+          <span className="size-2 rounded-full" style={{ backgroundColor: 'rgba(0, 93, 142, 0.2)' }} />
+        </div>
+
+        {/* 状态文本（可选） */}
+        {/* {status && <span className="text-sm text-gray-500">{status}</span>} */}
+      </div>
+    )
+  },
+}

package/src/components/LiveChatWidget/components/MessageContent/index.ts

@@ -0,0 +1,16 @@
+/**
+ * 消息内容渲染器统一导出
+ */
+
+export { MessageContent } from '../MessageContent'
+export { TextBlock } from './TextBlock'
+export { ProductCard } from './ProductCard'
+export { ProductList } from './ProductList'
+export { ProductComparison, ProductComparisonRenderer } from './ProductComparison'
+export { PolicyBlock } from './PolicyBlock'
+export { QuickReplies, createQuickRepliesRenderer } from './QuickReplies'
+export { ThinkingBlock } from './ThinkingBlock'
+export { ErrorBlock } from './ErrorBlock'
+export { FAQList, FAQListRenderer } from './FAQList.js'
+export { PromotionList, PromotionListRenderer } from './PromotionList.js'
+export { CartCard } from './CartCard.js'

package/src/components/LiveChatWidget/components/MessageContent.tsx

@@ -0,0 +1,113 @@
+/**
+ * 消息内容容器组件
+ * 根据消息内容类型分发到对应的渲染器
+ * 基于 specs/livechat-widget/plan.md 的消息内容渲染设计
+ */
+
+import React from 'react'
+import type { MessageContent as MessageContentType, MessageRenderer } from '../types'
+import { MessageRendererRegistry } from '../utils/messageRenderers'
+
+export interface MessageContentProps {
+  /**
+   * 消息内容
+   */
+  content: MessageContentType
+
+  /**
+   * 是否为用户消息
+   */
+  isUser: boolean
+
+  /**
+   * 是否为系统消息
+   */
+  isSystem: boolean
+
+  /**
+   * 自定义渲染器注册表
+   */
+  rendererRegistry?: MessageRendererRegistry
+
+  /**
+   * 默认渲染器（当找不到对应渲染器时使用）
+   */
+  defaultRenderer?: MessageRenderer
+
+  /**
+   * 自定义样式类名
+   */
+  className?: string
+
+  /**
+   * 商品添加到购物车回调
+   */
+  onAddToCart?: (product: any) => void
+}
+
+/**
+ * 默认渲染器 - 显示未知类型提示
+ */
+const defaultFallbackRenderer: MessageRenderer = {
+  render: content => <div className="text-sm italic text-gray-500">未知消息类型: {content.type}</div>,
+}
+
+/**
+ * 消息内容容器组件
+ *
+ * 功能：
+ * - 根据 content.type 分发到对应的渲染器
+ * - 支持自定义渲染器注册表
+ * - 提供默认兜底渲染器
+ *
+ * 渲染流程：
+ * 1. 检查自定义渲染器注册表是否有对应类型
+ * 2. 如果有，使用自定义渲染器
+ * 3. 如果没有，使用默认渲染器
+ * 4. 如果默认渲染器也没有，显示未知类型提示
+ *
+ * @example
+ * ```tsx
+ * <MessageContent
+ *   content={content}
+ *   isUser={message.role === 'user'}
+ *   isSystem={message.role === 'system'}
+ *   rendererRegistry={customRegistry}
+ * />
+ * ```
+ */
+export const MessageContent: React.FC<MessageContentProps> = ({
+  content,
+  isUser,
+  isSystem,
+  rendererRegistry,
+  defaultRenderer,
+  className = '',
+  onAddToCart,
+}) => {
+  // 动态注入 onAddToCart 到 product_card、product_list 和 product_comparison 类型的内容中
+  let processedContent = content
+  if (
+    (content.type === 'product_card' || content.type === 'product_list' || content.type === 'product_comparison') &&
+    onAddToCart
+  ) {
+    processedContent = {
+      ...content,
+      data: {
+        ...(content as any).data,
+        onAddToCart,
+      },
+    }
+  }
+
+  // 尝试从注册表获取渲染器
+  const customRenderer = rendererRegistry?.get(processedContent.type)
+
+  // 确定最终使用的渲染器
+  const renderer = customRenderer || defaultRenderer || defaultFallbackRenderer
+
+  // 渲染内容
+  const rendered = renderer.render(processedContent, isUser, isSystem)
+
+  return <div className={className}>{rendered}</div>
+}

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">No messages yet</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,36 @@
+/**
+ * LiveChat 组件常量定义
+ */
+
+import type { CommonText } from './types'
+
+/**
+ * 货币符号映射表
+ * 用于将货币代码转换为对应的符号
+ */
+export const CURRENCY_SYMBOLS: Record<string, string> = {
+    USD: "$",
+    CAD: "CA$",
+    GBP: "£",
+    EUR: "€",
+    AUD: "$",
+    SGD: "$",
+    NZD: "NZ$",
+    AED: "AED ",
+    VND: "₫",
+    TWD: "NT$",
+    PLN: "zł",
+    RON: "Lei"
+}
+
+/**
+ * 默认文案配置
+ */
+export const DEFAULT_COMMON_TEXT: Required<CommonText> = {
+  learnMore: 'Learn More',
+  showLess: 'Show Less',
+  addToCart: 'Add to Cart',
+  viewMore: 'View More',
+  off: 'OFF',
+  total: 'Total',
+}

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

@@ -0,0 +1,146 @@
+/**
+ * 聊天 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, type RecaptchaConfig } from '../api/chat'
+
+export interface UseChatAPIOptions {
+  /**
+   * API 基础 URL
+   */
+  apiBaseUrl: string
+
+  /**
+   * 自定义请求头
+   */
+  headers?: Record<string, string>
+
+  /**
+   * reCAPTCHA 配置
+   */
+  recaptchaConfig?: RecaptchaConfig
+
+  /**
+   * 错误处理回调
+   */
+  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, headers, recaptchaConfig, 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, headers, recaptchaConfig)
+      } 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, headers, recaptchaConfig, onError]
+  )
+
+  /**
+   * 创建新会话或恢复现有会话
+   */
+  const createSession = useCallback(
+    async (request: NewSessionRequest): Promise<NewSessionResponse> => {
+      try {
+        return await createNewSession(apiBaseUrl, request, headers, recaptchaConfig)
+      } catch (error) {
+        console.error('[useChatAPI] Create session error:', error)
+        onError?.(error as Error)
+        throw error
+      }
+    },
+    [apiBaseUrl, headers, recaptchaConfig, onError]
+  )
+
+  /**
+   * 中断当前的 SSE 流
+   */
+  const abortStream = useCallback(() => {
+    if (abortControllerRef.current) {
+      abortControllerRef.current.abort()
+      abortControllerRef.current = null
+      isSendingRef.current = false
+    }
+  }, [])
+
+  return {
+    sendMessageStream,
+    createSession,
+    abortStream,
+    isSending: isSendingRef.current,
+  }
+}