Ordo UI
AI助手与对话

AssistantHistoryMenu

@mox-hub/patterns · AI · 助手与对话 · canonical

assistant-history-menu@mox-hub/patternsAI Executioncanonicalsrc/components/assistant-history-menu.tsx
变体演示assistant-history-menu

Props API

Prop类型默认值说明
conversations*AssistantConversationSummary[]——
isLoading*boolean——
activeConversationId*string——
currentConversationId*string——
onSelect*(id: string) => void——
onCreate*() => void——
labels*Partial<AssistantHistoryLabels>——
formatUpdatedAt*(updatedAt: string) => string——

源码

packages/patterns/src/components/assistant-history-menu.tsx
/**
 * 历史对话菜单 —— 头部时钟按钮弹出:新建对话 + 历史会话列表(相对时间,
 * 当前会话高亮;点选切换、空会话显示「新对话」占位)。
 * AssistantHistoryList 独立导出便于测试。
 *
 * 库内不依赖 ordo API 类型/i18n:会话摘要与文案均由 props 注入。
 */
import { History, SquarePen } from 'lucide-react'
import { cn } from '@mox-hub/ui'
import { Button } from '@mox-hub/ui/components/button'
import {
  Popover,
  PopoverContent,
  PopoverTrigger,
} from '@mox-hub/ui/components/popover'
import { ScrollArea } from '@mox-hub/ui/components/scroll-area'
import { HeaderActionButton } from './header-action-button'
import { formatRelative } from '@mox-hub/ui/format'
import { useFormatters, useI18n } from '@mox-hub/ui/i18n'
import { usePatternLabels } from '../lib/i18n'

/** 历史会话摘要(与 ordo AssistantConversationSummary 结构兼容) */
export interface AssistantConversationSummary {
  id: string
  title?: string | null
  projectId?: string | null
  messageCount: number
  createdAt: string
  updatedAt: string
}

/** 组件内文案缺省(中文常量;消费方经 labels 覆写接入 i18n)。 */
export interface AssistantHistoryLabels {
  new: string
  empty: string
  untitled: string
  open: string
}

export const ASSISTANT_HISTORY_DEFAULT_LABELS: AssistantHistoryLabels = {
  new: '新建对话',
  empty: '还没有历史对话',
  untitled: '新对话',
  open: '历史对话',
}

export function AssistantHistoryList({
  conversations,
  isLoading,
  activeConversationId,
  currentConversationId,
  onSelect,
  onCreate,
  labels,
  formatUpdatedAt,
}: {
  conversations: AssistantConversationSummary[]
  isLoading?: boolean
  /** 菜单持有者当前展示的会话(跟随模式为 currentConversationId) */
  activeConversationId: string | null
  /** 服务端「当前会话」(最新 updatedAt),空会话占位与高亮用它兜底 */
  currentConversationId: string | null
  onSelect: (id: string) => void
  onCreate: () => void
  /** 文案覆写(默认 zh-CN;主仓 i18n 适配层集中传入 t() 结果)。 */
  labels?: Partial<AssistantHistoryLabels>
  /** 更新时间格式化器:主仓传 i18n 相对时间;缺省 formatRelative(跟随默认语言)。 */
  formatUpdatedAt?: (updatedAt: string) => string
}) {
  const D = usePatternLabels('assistantHistory', ASSISTANT_HISTORY_DEFAULT_LABELS)
  const F = useFormatters()
  const { locale } = useI18n()
  const text = {
    new: labels?.new ?? D.new,
    empty: labels?.empty ?? D.empty,
    untitled: labels?.untitled ?? D.untitled,
  }
  const format =
    formatUpdatedAt ?? ((updatedAt: string) => formatRelative(updatedAt, { locale }))

  return (
    <div className="flex flex-col gap-1" data-ai-component="assistant.history-list">
      <Button
        type="button"
        variant="outline"
        disabled={isLoading}
        onClick={onCreate}
        className="h-8 justify-start gap-2 text-xs"
        data-ai-action="assistant.history.new.click"
      >
        <SquarePen className="size-3.5" />
        {text.new}
      </Button>
      {isLoading ? null : conversations.length === 0 ? (
        <p className="px-2 py-3 text-2xs text-content-text-muted">{text.empty}</p>
      ) : (
        // overlay 细滚动条:不占列表内容宽度(max-h 约束落在 viewport,Root 随内容自适应)
        <ScrollArea
          overscrollContain
          className="[&_[data-slot=scroll-area-viewport]]:max-h-100"
          contentClassName="pe-2"
        >
          {conversations.map((conversation) => {
            const isActive = conversation.id === (activeConversationId ?? currentConversationId)
            const title =
              conversation.messageCount > 0 && conversation.title
                ? conversation.title
                : text.untitled
            const relative = format(conversation.updatedAt)
            return (
              <Button
                key={conversation.id}
                type="button"
                variant="ghost"
                onClick={() => onSelect(conversation.id)}
                aria-current={isActive ? 'true' : undefined}
                className={cn(
                  'h-auto w-full justify-between gap-2 px-2 py-1.5 text-start font-normal',
                  isActive && 'bg-accent',
                )}
              >
                <span
                  className="min-w-0 flex-1 truncate text-label text-content-text"
                  title={title}
                >
                  {title}
                </span>
                <span className="shrink-0 text-caption whitespace-nowrap text-content-text-muted">
                  {relative || F.date(conversation.updatedAt)}
                </span>
              </Button>
            )
          })}
        </ScrollArea>
      )}
    </div>
  )
}

export function AssistantHistoryMenu({
  conversations,
  isLoading,
  activeConversationId,
  currentConversationId,
  onSelect,
  onCreate,
  labels,
  formatUpdatedAt,
}: {
  conversations: AssistantConversationSummary[]
  isLoading?: boolean
  activeConversationId: string | null
  currentConversationId: string | null
  onSelect: (id: string) => void
  onCreate: () => void
  /** 文案覆写(默认 zh-CN;主仓 i18n 适配层集中传入 t() 结果)。 */
  labels?: Partial<AssistantHistoryLabels>
  /** 更新时间格式化器:主仓传 i18n 相对时间;缺省 formatRelative(跟随默认语言)。 */
  formatUpdatedAt?: (updatedAt: string) => string
}) {
  const D = usePatternLabels('assistantHistory', ASSISTANT_HISTORY_DEFAULT_LABELS)
  const openLabel = labels?.open ?? D.open

  return (
    <Popover>
      <PopoverTrigger
        render={<HeaderActionButton icon={History} label={openLabel} />}
      />
      <PopoverContent align="end" className="w-72 p-2">
        <AssistantHistoryList
          conversations={conversations}
          isLoading={isLoading}
          activeConversationId={activeConversationId}
          formatUpdatedAt={formatUpdatedAt}
          currentConversationId={currentConversationId}
          onSelect={onSelect}
          onCreate={onCreate}
          labels={labels}
        />
      </PopoverContent>
    </Popover>
  )
}

可访问性与 RTL

  • 键盘:交互件保留:focus-visible焦点环;浮层支持 Escape 关闭与焦点归还,菜单 / 页签按 Base UI 约定支持方向键。 筛选菜单、拖拽排序、执行树与模型 listbox 等关键键盘流由 Playwright 断言覆盖,见规范示例 · 交互与可访问性。
  • RTL:间距、对齐与方向性图标使用逻辑属性 (ms-* /text-start /rtl:-scale-x-100);通过 ThemeProvider 或I18nProvider 的direction="rtl"驱动,`lint:rtl` 会拦截新增物理类。
  • 文案:优先用组件labels /translate /translator props,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。
  • 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。

用法说明

历史对话菜单:新建 + 会话列表(相对时间/高亮/空态);会话摘要与 labels 由 props 注入,不依赖 API 或 i18n。