Ordo UI
AI助手与对话

Suggestion

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

suggestion@mox-hub/patternsSemanticcanonicalsrc/components/suggestion.tsx
变体演示suggestion

Props API

Prop类型默认值说明
items*SuggestionItem[]——
onSelect*(item: SuggestionItem) => void——
disabled*booleanfalse—
loading*booleanfalse—
emptyLabel*string——
labels*Partial<SuggestionLabels>——
className*string——

源码

packages/patterns/src/components/suggestion.tsx
import type { ReactNode } from 'react';

import { cn } from '@mox-hub/ui';
import { Button } from '@mox-hub/ui/components/button';
import { Spinner } from '@mox-hub/ui/components/spinner';

import { usePatternLabels } from '../lib/i18n';

/**
 * Suggestion —— 通用建议 chips(对话 / AI 平面,W4 P1 / B14)。
 *
 * 可换行的建议按钮列表,覆盖快捷问法、下一步动作、追问提示等场景:
 * 点选即回调 `onSelect`,由消费方决定「填入输入框」还是「立即发送」。
 * 本件用于后续替换 `assistant-quick-prompts` 的内部实现,但自身不依赖它。
 *
 * 边界:
 * - 纯展示 / 受控件,不取数、不发请求;loading / 空态由 props 驱动;
 * - 建议项的外观(图标 / 描述)由 `SuggestionItem` 描述,不自造业务语义;
 * - a11y:列表为 `role="list"`、条目为 `listitem`,按钮原生可聚焦、可键盘触发。
 */
export interface SuggestionItem {
  id: string;
  label: string;
  description?: string;
  icon?: ReactNode;
}

export interface SuggestionLabels {
  /** 列表区域无障碍名 */
  region: string;
  /** 空列表文案 */
  empty: string;
  /** 加载中文案 */
  loading: string;
}

export const SUGGESTION_DEFAULT_LABELS: SuggestionLabels = {
  region: '建议',
  empty: '暂无建议',
  loading: '正在生成建议…',
};

export interface SuggestionProps {
  items: SuggestionItem[];
  /** 点选建议(回调携带完整 item,便于消费方区分 id 与文案) */
  onSelect: (item: SuggestionItem) => void;
  disabled?: boolean;
  /** 加载中优先于空态展示 */
  loading?: boolean;
  /** 覆写空列表文案(优先级高于 labels.empty) */
  emptyLabel?: string;
  labels?: Partial<SuggestionLabels>;
  className?: string;
}

export function Suggestion({
  items,
  onSelect,
  disabled = false,
  loading = false,
  emptyLabel,
  labels,
  className,
}: SuggestionProps) {
  const D = usePatternLabels('suggestion', SUGGESTION_DEFAULT_LABELS);
  const text: SuggestionLabels = {
    region: labels?.region ?? D.region,
    empty: labels?.empty ?? D.empty,
    loading: labels?.loading ?? D.loading,
  };

  return (
    <div
      data-ai-component="suggestion"
      className={cn('w-full', className)}
    >
      {loading ? (
        <div className="flex items-center gap-2 text-xs text-content-text-muted">
          <Spinner size="sm" label={text.loading} />
          <span>{text.loading}</span>
        </div>
      ) : items.length === 0 ? (
        <p className="text-xs text-content-text-muted">
          {emptyLabel ?? text.empty}
        </p>
      ) : (
        <ul aria-label={text.region} className="flex flex-wrap gap-1.5">
          {items.map((item) => (
            <li key={item.id} className="min-w-0 max-w-full">
              <Button
                type="button"
                variant="outline"
                size="xs"
                disabled={disabled}
                onClick={() => onSelect(item)}
                className="h-auto max-w-full rounded-full px-2.5 py-1 text-xs font-normal text-content-text-secondary"
              >
                {item.icon ? (
                  <span
                    aria-hidden
                    className="flex shrink-0 items-center [&_svg:not([class*='size-'])]:size-3"
                  >
                    {item.icon}
                  </span>
                ) : null}
                <span className="min-w-0 truncate">{item.label}</span>
                {item.description ? (
                  <span className="min-w-0 truncate text-2xs text-content-text-muted">
                    {item.description}
                  </span>
                ) : null}
              </Button>
            </li>
          ))}
        </ul>
      )}
    </div>
  );
}

可访问性与 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。

用法说明

通用建议 chips:items 注入、loading/empty/disabled、onSelect 回调;替代产品专用的快捷问法内部实现。