Ordo UI
AI执行与编排

TaskPlan

@mox-hub/patterns · AI · 执行与编排 · canonical

task-plan@mox-hub/patternsAI Executioncanonicalsrc/components/task-plan.tsx
变体演示task-plan
  1. 确认登录页现状
    已完成
  2. 拆解验收标准
    小码执行中
  3. 生成测试用例
    待执行
  4. 运行冒烟测试

    端口占用

    失败

Props API

Prop类型默认值说明
items*TaskPlanItem[]——
title*string——
collapsible*booleantrue—
defaultOpen*booleantrue—
open*boolean——
onOpenChange*(open: boolean) => void——
onItemClick*(item: TaskPlanItem) => void——
renderItemExtra*(item: TaskPlanItem) => ReactNode——
labels*Partial<TaskPlanLabels>——
className*string——

源码

packages/patterns/src/components/task-plan.tsx
import { useId, useState, type ComponentProps, type ReactNode } from 'react';
import {
  CheckCircle2,
  ChevronDown,
  Circle,
  MinusCircle,
  XCircle,
} from 'lucide-react';

import { cn } from '@mox-hub/ui';
import {
  Collapsible,
  CollapsibleContent,
  CollapsibleTrigger,
} from '@mox-hub/ui/components/collapsible';
import { Spinner } from '@mox-hub/ui/components/spinner';

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

/**
 * TaskPlan —— 计划执行清单(执行平面 / 对话平面共用)。
 *
 * 把 agent 的 plan(todos)实时打勾:
 * - 五态:pending / in_progress / completed / failed / skipped;
 * - 进度条与计数从 items 现算,不接收预汇总值(两处口径必漂移);
 * - 折叠只隐藏行,计数与进度仍按全量计算(折叠不隐账);
 * - 状态变化经 `role="status"` 汇总行播报,单行状态另有文本标签,不只靠颜色。
 */
export type TaskPlanStatus =
  | 'pending'
  | 'in_progress'
  | 'completed'
  | 'failed'
  | 'skipped';

export interface TaskPlanItem {
  id: string;
  title: string;
  description?: string;
  status: TaskPlanStatus;
  /** 归属 agent(多 agent 场景显示) */
  agentName?: string;
  /** 结果 / 错误摘要 */
  result?: string;
}

export interface TaskPlanLabels {
  /** 无障碍名 */
  region: string;
  progress: (done: number, total: number) => string;
  expand: string;
  collapse: string;
  pending: string;
  inProgress: string;
  completed: string;
  failed: string;
  skipped: string;
  empty: string;
}

export const TASK_PLAN_DEFAULT_LABELS: TaskPlanLabels = {
  region: '执行计划',
  progress: (done, total) => `${done}/${total} 已完成`,
  expand: '展开计划',
  collapse: '收起计划',
  pending: '待执行',
  inProgress: '执行中',
  completed: '已完成',
  failed: '失败',
  skipped: '已跳过',
  empty: '暂无计划',
};

const STATUS_ICON = {
  pending: Circle,
  completed: CheckCircle2,
  failed: XCircle,
  skipped: MinusCircle,
} as const;

const STATUS_TEXT_CLASS: Record<TaskPlanStatus, string> = {
  pending: 'text-content-text-muted',
  in_progress: 'text-accent-blue',
  completed: 'text-accent-green',
  failed: 'text-accent-red',
  skipped: 'text-content-text-muted',
};

export interface TaskPlanProps extends Omit<ComponentProps<'div'>, 'children'> {
  items: TaskPlanItem[];
  /** 标题;不传则不渲染头部 */
  title?: string;
  /** 可折叠;默认 true */
  collapsible?: boolean;
  /** 非受控初始展开态;默认展开 */
  defaultOpen?: boolean;
  /** 受控展开态 */
  open?: boolean;
  onOpenChange?: (open: boolean) => void;
  /** 单行点击 */
  onItemClick?: (item: TaskPlanItem) => void;
  /** 行尾附加内容 */
  renderItemExtra?: (item: TaskPlanItem) => ReactNode;
  labels?: Partial<TaskPlanLabels>;
}

export function TaskPlan({
  items,
  title,
  collapsible = true,
  defaultOpen = true,
  open,
  onOpenChange,
  onItemClick,
  renderItemExtra,
  labels,
  className,
  ...props
}: TaskPlanProps) {
  const D = usePatternLabels('taskPlan', TASK_PLAN_DEFAULT_LABELS);
  const text: TaskPlanLabels = {
    region: labels?.region ?? D.region,
    progress: labels?.progress ?? D.progress,
    expand: labels?.expand ?? D.expand,
    collapse: labels?.collapse ?? D.collapse,
    pending: labels?.pending ?? D.pending,
    inProgress: labels?.inProgress ?? D.inProgress,
    completed: labels?.completed ?? D.completed,
    failed: labels?.failed ?? D.failed,
    skipped: labels?.skipped ?? D.skipped,
    empty: labels?.empty ?? D.empty,
  };

  const statusLabel: Record<TaskPlanStatus, string> = {
    pending: text.pending,
    in_progress: text.inProgress,
    completed: text.completed,
    failed: text.failed,
    skipped: text.skipped,
  };

  const controlled = open !== undefined;
  const [innerOpen, setInnerOpen] = useState(defaultOpen);
  const currentOpen = controlled ? open : innerOpen;
  const panelId = useId();

  const total = items.length;
  const done = items.filter((item) => item.status === 'completed').length;
  const ratio = total > 0 ? done / total : 0;

  const handleOpenChange = (next: boolean) => {
    if (!controlled) setInnerOpen(next);
    onOpenChange?.(next);
  };

  const list = (
    <ol className="space-y-1.5">
      {items.map((item) => {
        const running = item.status === 'in_progress';
        const Icon = running ? null : STATUS_ICON[item.status];
        return (
          <li
            key={item.id}
            data-ai-component="task-plan.item"
            data-status={item.status}
            className="flex items-start gap-2"
          >
            <span
              className={cn(
                'mt-0.5 flex size-4 shrink-0 items-center justify-center',
                STATUS_TEXT_CLASS[item.status],
              )}
              aria-hidden
            >
              {running ? (
                <Spinner size="sm" className="size-3.5" />
              ) : Icon ? (
                <Icon className="size-3.5" />
              ) : (
                <Circle className="size-3.5" />
              )}
            </span>

            <div className="min-w-0 flex-1">
              {onItemClick ? (
                <button
                  type="button"
                  className="block w-full cursor-pointer rounded-md text-start text-xs text-content-text outline-none transition-colors duration-fast hover:text-accent-blue focus-visible:ring-2 focus-visible:ring-ring/50"
                  onClick={() => onItemClick(item)}
                >
                  {item.title}
                </button>
              ) : (
                <span
                  className={cn(
                    'block text-xs',
                    item.status === 'completed'
                      ? 'text-content-text-secondary line-through'
                      : item.status === 'skipped'
                        ? 'text-content-text-muted line-through'
                        : 'text-content-text',
                  )}
                >
                  {item.title}
                </span>
              )}

              {item.description ? (
                <p className="mt-0.5 text-2xs text-content-text-muted">
                  {item.description}
                </p>
              ) : null}

              {item.result ? (
                <p
                  className={cn(
                    'mt-0.5 break-words text-2xs',
                    item.status === 'failed'
                      ? 'text-accent-red'
                      : 'text-content-text-secondary',
                  )}
                >
                  {item.result}
                </p>
              ) : null}
            </div>

            {item.agentName ? (
              <span className="shrink-0 text-2xs text-content-text-muted">
                {item.agentName}
              </span>
            ) : null}

            <span className="shrink-0 text-2xs text-content-text-muted">
              {statusLabel[item.status]}
            </span>

            {renderItemExtra ? renderItemExtra(item) : null}
          </li>
        );
      })}
    </ol>
  );

  const summary = (
    <div className="flex min-w-0 flex-1 items-center gap-2">
      {title ? (
        <span className="truncate text-xs font-semibold text-content-text">
          {title}
        </span>
      ) : null}
      <span
        role="status"
        aria-live="polite"
        className="shrink-0 text-2xs tabular-nums text-content-text-muted"
      >
        {text.progress(done, total)}
      </span>
      <span className="relative h-1 min-w-8 flex-1 overflow-hidden rounded-full bg-muted">
        <span
          className="absolute inset-y-0 start-0 rounded-full bg-accent-green transition-[width] duration-normal"
          style={{ width: `${Math.round(ratio * 100)}%` }}
          aria-hidden
        />
      </span>
    </div>
  );

  if (total === 0) {
    return (
      <div
        data-ai-component="task-plan"
        className={cn(
          'rounded-lg border border-content-border bg-content-bg-secondary px-3 py-2 text-xs text-content-text-muted',
          className,
        )}
        {...props}
      >
        {text.empty}
      </div>
    );
  }

  if (!collapsible) {
    return (
      <div
        role="region"
        aria-label={text.region}
        data-ai-component="task-plan"
        className={cn(
          'rounded-lg border border-content-border bg-content-bg p-3',
          className,
        )}
        {...props}
      >
        <div className="mb-2 flex items-center">{summary}</div>
        {list}
      </div>
    );
  }

  return (
    <div
      role="region"
      aria-label={text.region}
      data-ai-component="task-plan"
      className={cn(
        'rounded-lg border border-content-border bg-content-bg',
        className,
      )}
      {...props}
    >
      <Collapsible open={currentOpen} onOpenChange={handleOpenChange}>
        <CollapsibleTrigger
          className="flex w-full items-center gap-2 rounded-lg px-3 py-2 text-start outline-none transition-colors duration-fast hover:bg-muted focus-visible:ring-2 focus-visible:ring-ring/50"
          aria-controls={panelId}
          aria-label={currentOpen ? text.collapse : text.expand}
        >
          {summary}
          <ChevronDown
            aria-hidden
            className={cn(
              'size-3.5 shrink-0 text-content-text-muted transition-transform duration-fast',
              currentOpen && 'rotate-180',
            )}
          />
        </CollapsibleTrigger>
        <CollapsibleContent
          id={panelId}
          className="border-t border-content-border px-3 py-2"
        >
          {list}
        </CollapsibleContent>
      </Collapsible>
    </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。

用法说明

计划执行清单:五态 pending/in_progress/completed/failed/skipped;进度从 items 现算,折叠不隐账;状态有文本标签,不只靠颜色。