Ordo UI
AI执行与编排

DecisionQueuePanel

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

decision-queue-panel@mox-hub/patternsAI Executioncanonicalsrc/components/decision-queue-panel.tsx
变体演示decision-queue-panel

该你了

阻断 1排队 1
来自通知中心同一端点

另有 1 项未显示(本次取出 2 / 共 3)

Props API

Prop类型默认值说明
queue*DecisionQueue——
isPending*boolean——
isError*boolean——
sourceNote*string——
onAction*(action: string, d: DecisionQueueItem, opts?: { reason?: string; answer?: string; }) => void——
busyId*string——
readOnly*booleanfalse—
readOnlyNote*string——
waitingNowMs*number——
renderDecision*(decision: DecisionQueueItem, ctx: DecisionRenderContext) => ReactNode——
labels*Partial<DecisionQueuePanelLabels>——

源码

packages/patterns/src/components/decision-queue-panel.tsx
import { useState } from 'react';
import { ChevronDown, ChevronRight } from 'lucide-react';
import { cn } from '@mox-hub/ui';
import type { ReactNode } from 'react';
import { TONE_CLASS } from '@mox-hub/ui/components/tone';
import { usePatternLabels, usePatternTranslate } from '../lib/i18n';
import { createTranslator, type PatternTranslate } from '../lib/translate';

export interface DecisionQueuePanelLabels {
  panel: string;
  title: string;
  statusError: string;
  statusLoading: string;
  blocking: string;
  advisory: string;
  blockingTitle: string;
  advisoryTitle: string;
  error: string;
  loading: string;
  empty: string;
  hidden: (count: number, shown: number, total: number) => string;
  createdAt: (value: string) => string;
}

const DEFAULT_LABELS: DecisionQueuePanelLabels = {
  panel: '待你拍板',
  title: '该你了',
  statusError: '待办读取失败(不显示占位数据)',
  statusLoading: '读取中',
  blocking: '阻断',
  advisory: '排队',
  blockingTitle: '紧迫度 blocking:执行已暂停等待裁决',
  advisoryTitle: '紧迫度 advisory:排队判断题,不挡其他工作推进',
  error: '待你拍板的事项读取失败。不显示占位条目,以免被当成真实待办;请检查网络或稍后重试。',
  loading: '正在读取待办…',
  empty: '没有待你拍板的事项',
  hidden: (count, shown, total) =>
    `另有 ${count} 项未显示(本次取出 ${shown} / 共 ${total})`,
  createdAt: (value) => `创建于 ${value}`,
};

/**
 * 「该你了」待办区(ARCH-AISURFACE-001 §3.1 右栏 / §3.2 待拍板决策卡就地展开)。
 *
 * ## 纪律:不开第二个拍板入口
 *
 * 展开态直接复用 `DecisionCard`(= `DecisionCardShell` 五段式 + 各 kind 槽位),
 * 决议经 `useResolveDecision` → **既有**端点(approval / acceptance / proposals
 * 各自的原生写路径)。本组件**不**自建动作栏、**不**直连 api、**不**改决策语义——
 * 「就地拍板」的增量价值只是**不跳页**,写路径必须与决策收件箱完全一致。
 *
 * ## 诚实粒度
 *
 * · 三类「空」分开说:读取中 / 读取失败 / 确实没有待你拍板的事;
 * · 分页截断如实报(`另有 N 项未显示`),不假装列表就是全部;
 * · 等待时长由真实 `createdAt` 推出,**不**编造"剩余时限"(无该字段)。
 */

/** 待决队列条目最小投影(与 ordo Decision 结构兼容)。 */
export interface DecisionQueueItem {
  id: string;
  kind: string;
  title: string;
  urgency?: string;
  createdAt: string;
  projectName?: string;
  [key: string]: unknown;
}

export interface DecisionQueue {
  items: DecisionQueueItem[];
  total: number;
  blocking: number;
  advisory: number;
  hiddenCount: number;
}

export interface DecisionRenderContext {
  onAction: (action: string, d: DecisionQueueItem, opts?: { reason?: string; answer?: string }) => void;
  busy: boolean;
  readOnly: boolean;
  readOnlyNote?: string;
}

/**
 * 等待时长人话化;`createdAt` 不可解析时返回 null(→ 显示破折号,不猜)。
 *
 * 参考时刻缺省取当前时刻。**取默认值这件事刻意留在函数体里**:读时钟是个不纯操作,
 * 而 React 的纯度规则禁止在渲染期直接调用(`react-hooks/purity` 会直接报错)。
 * 调用方若要一个非"现在"的参考时刻(回放态取**剧本时钟**),必须显式传 `nowMs`。
 */
const WAITING_LABELS = {
  justNow: '刚刚',
  minutes: '{{count}} 分钟',
  hours: '{{count}} 小时',
  days: '{{count}} 天',
};

export function formatWaiting(
  createdAt: string,
  nowMs?: number,
  t?: PatternTranslate,
): string | null {
  const parsed = Date.parse(createdAt);
  if (Number.isNaN(parsed)) return null;
  const now = nowMs ?? Date.now();
  const mins = Math.max(0, Math.floor((now - parsed) / 60000));
  const tr = t ?? createTranslator(WAITING_LABELS);
  if (mins < 1) return tr('justNow');
  if (mins < 60) return tr('minutes', { count: mins });
  const hours = Math.floor(mins / 60);
  if (hours < 24) return tr('hours', { count: hours });
  return tr('days', { count: Math.floor(hours / 24) });
}

/**
 * 待办区的**渲染本体**:只吃 props,不碰任何 hook。
 *
 * 抽出它的是 S5 回放:回放要放**同一块待办区**,但数据来自剧本帧。理由同泳道
 * (见 `pipeline-lane-strip.tsx`)——演示给新手看的那块界面,必须就是真实项目里
 * 那一块,而不是"照着它另画的一块"。
 *
 * ## `readOnly`:回放里不能有能按的动作键
 *
 * 剧本里的决策是**已发生事实的复述**,其 `id` 在服务端并不存在。若照常渲染动作栏,
 * 点下去的每一下都是"看起来批了、其实什么都没落"——正是 S2-e 删掉那个假「准入」
 * 按钮时定下的同一类错误。故回放态**整条动作栏不渲染**,并在原处写明为什么。
 */
export function DecisionQueuePanelView({
  queue,
  isPending,
  isError,
  sourceNote,
  onAction,
  busyId,
  readOnly = false,
  readOnlyNote,
  waitingNowMs,
  renderDecision,
  labels,
}: {
  queue: DecisionQueue;
  isPending: boolean;
  isError: boolean;
  /** 表头出处注脚。回放态必须写明数据不是从收件箱取的 */
  sourceNote: string;
  onAction: (action: string, d: DecisionQueueItem, opts?: { reason?: string; answer?: string }) => void;
  /** 决策卡渲染器:主仓注入 DecisionCard,库内不依赖决策实现。 */
  renderDecision: (decision: DecisionQueueItem, ctx: DecisionRenderContext) => ReactNode;
  busyId: string | null;
  /** 只读预览(回放):不渲染动作栏 */
  readOnly?: boolean;
  /** 只读时在原动作栏位置给出的说明(调用方给文案,避免为回放另起 i18n 管道) */
  readOnlyNote?: string;
  /**
   * 「等待时长」的参考时刻,缺省取当前时刻。
   *
   * 回放态必须传**剧本时刻**:等待时长是 `createdAt` 与"现在"的差值,而在回放里
   * 唯一有意义的时钟是剧本自己的时钟。若沿用墙上时间,一条剧本里刚出现的待办会
   * 显示「等了 4 天」——一个精确、具体、而且与屏幕上其他每一处都矛盾的读数。
   */
  waitingNowMs?: number;
  labels?: Partial<DecisionQueuePanelLabels>;
}) {
  const L = { ...DEFAULT_LABELS, ...labels };
  const [expandedId, setExpandedId] = useState<string | null>(null);

  // 表头状态是**出处/健康**注脚,正文才是内容态——两者措辞须不同,
  // 否则同一句话在一屏里出现两遍(读起来像复读,也让人分不清是哪一层的状态)
  const statusText = isError
    ? L.statusError
    : isPending
      ? L.statusLoading
      : sourceNote;

  return (
    <section
      className="w-full"
      data-ai-component="ai-surface.decision-queue"
      data-ai-role="panel"
      aria-label={L.panel}
    >
      <div className="mb-2 flex items-center justify-between px-1">
        <div className="flex items-center gap-2">
          <h2 className="text-xs font-semibold tracking-tight text-foreground">{L.title}</h2>
          {!isPending && !isError && (
            <span className="flex items-center gap-1 font-mono text-xs">
              <span
                className={cn(
                  'rounded-full px-1.5 py-0.5',
                  queue.blocking > 0 ? TONE_CLASS.danger.light : TONE_CLASS.success.light,
                )}
                title={L.blockingTitle}
              >
                {L.blocking} {queue.blocking}
              </span>
              <span
                className={cn('rounded-full px-1.5 py-0.5', TONE_CLASS.default.light)}
                title={L.advisoryTitle}
              >
                {L.advisory} {queue.advisory}
              </span>
            </span>
          )}
        </div>
        <span className="font-mono text-xs text-muted-foreground">{statusText}</span>
      </div>

      {isError ? (
        <p className="rounded-xl border border-foreground/10 bg-foreground/5 px-3 py-3 text-xs text-muted-foreground">
          {L.error}
        </p>
      ) : isPending ? (
        <p className="rounded-xl border border-foreground/10 bg-foreground/5 px-3 py-3 text-xs text-muted-foreground">
          {L.loading}
        </p>
      ) : queue.items.length === 0 ? (
        <p className="rounded-xl border border-foreground/10 bg-foreground/5 px-3 py-3 text-xs text-muted-foreground">
          {L.empty}
        </p>
      ) : (
        <ul className="space-y-1.5">
          {queue.items.map((decision) => (
            <QueueRow
              key={decision.id}
              decision={decision}
              expanded={expandedId === decision.id}
              busy={busyId === decision.id}
              renderDecision={renderDecision}
              onToggle={() =>
                setExpandedId((prev) => (prev === decision.id ? null : decision.id))
              }
              onAction={onAction}
              readOnly={readOnly}
              readOnlyNote={readOnlyNote}
              waitingNowMs={waitingNowMs}
              labels={L}
            />
          ))}
        </ul>
      )}

      {queue.hiddenCount > 0 && (
        <p className="mt-1.5 px-1 font-mono text-xs text-muted-foreground">
          {L.hidden(queue.hiddenCount, queue.items.length, queue.total)}
        </p>
      )}
    </section>
  );
}

function QueueRow({
  decision,
  expanded,
  busy,
  onToggle,
  onAction,
  renderDecision,
  readOnly,
  readOnlyNote,
  waitingNowMs,
  labels,
}: {
  decision: DecisionQueueItem;
  expanded: boolean;
  busy: boolean;
  onToggle: () => void;
  onAction: (action: string, d: DecisionQueueItem, opts?: { reason?: string; answer?: string }) => void;
  renderDecision: (decision: DecisionQueueItem, ctx: DecisionRenderContext) => ReactNode;
  readOnly: boolean;
  readOnlyNote?: string;
  waitingNowMs?: number;
  labels: DecisionQueuePanelLabels;
}) {
  const isBlocking = decision.urgency === 'blocking';
  const translate = usePatternTranslate('decisionQueuePanel', WAITING_LABELS);
  const waiting = formatWaiting(decision.createdAt, waitingNowMs, translate);

  return (
    <li
      className={cn(
        'overflow-hidden rounded-xl border border-foreground/10 bg-foreground/5',
        isBlocking && 'border-s-2 border-s-accent-red',
      )}
      data-ai-component="ai-surface.decision-row"
      data-decision-id={decision.id}
      // 就地解释(CAP-C-07):行本身此前只有 `data-decision-id`,而 AISlot 读的是
      // `data-ai-entity` 的 `kind:id`——**收起状态**下 Ctrl+左键无效(展开后是
      // DecisionCardShell 带出来的同名属性,属另一条路径)。这里补的是"没展开也想问"
      // 的那一半。注意前缀:决策卡壳的既有约定是 `decision:`,不能裸用 data-decision-id
      data-ai-entity={`decision:${decision.id}`}
    >
      <button
        type="button"
        onClick={onToggle}
        className="flex w-full cursor-pointer items-center gap-2 px-2.5 py-2 text-start transition-colors hover:bg-muted"
        aria-expanded={expanded}
        data-ai-action={`ai-surface.decision.${decision.kind}.toggle`}
      >
        {expanded ? (
          <ChevronDown className="size-3 shrink-0 text-muted-foreground" />
        ) : (
          <ChevronRight className="size-3 shrink-0 text-muted-foreground rtl:-scale-x-100" />
        )}
        <span
          className={cn(
            'shrink-0 rounded-full px-1.5 py-0.5 font-mono text-xs',
            isBlocking ? TONE_CLASS.danger.light : TONE_CLASS.default.light,
          )}
        >
          {decision.kind}
        </span>
        <span className="min-w-0 flex-1 truncate text-xs text-foreground">{decision.title}</span>
        {decision.projectName ? (
          <span className="shrink-0 font-mono text-xs text-muted-foreground">
            {decision.projectName}
          </span>
        ) : null}
        {/* 等待时长由真实 createdAt 推出;不可解析时给破折号,不猜 */}
        <span
          className="shrink-0 font-mono text-xs text-muted-foreground"
          title={labels.createdAt(decision.createdAt)}
        >
          {waiting ?? '—'}
        </span>
      </button>

      {/* 就地展开:既有决策卡文法(五段式 + 各 kind 槽位),写路径同收件箱 */}
      {expanded && (
        <div className="px-2.5 pb-2.5">
          {renderDecision(decision, { onAction, busy, readOnly, readOnlyNote })}
        </div>
      )}
    </li>
  );
}

/** 与原组件同名出口:props 驱动版本(数据/动作由消费方注入)。 */
export function DecisionQueuePanel(
  props: Parameters<typeof DecisionQueuePanelView>[0],
) {
  const D = usePatternLabels('decisionQueuePanel', DEFAULT_LABELS);
  return (
    <DecisionQueuePanelView
      {...props}
      labels={{ ...D, ...props.labels }}
    />
  );
}

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

用法说明

「该你了」待办区:queue 三态 + 阻断/排队计数 + 分页截断如实报;决策卡经 renderDecision 注入,动作走 onAction。