Ordo UI
AI助手与对话

ApplyDiff

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

apply-diff@mox-hub/patternsSemanticcanonicalsrc/components/apply-diff.tsx
变体演示apply-diff
你好,世界Ordo

Props API

Prop类型默认值说明
before*string——
after*string——
applied*booleanfalse—
busy*booleanfalse—
readOnly*booleanfalse—
onApply*() => void | Promise<void>——
onReject*() => void——
onRevert*() => void——
labels*Partial<ApplyDiffLabels>——
className*string——

源码

packages/patterns/src/components/apply-diff.tsx
/**
 * ApplyDiff - [AI] 整份文本变更的应用 / 拒绝 / 回退收口件(治理方案 W4 P1 · B8)
 *
 * 与同目录两件的分工:
 * - `inline-diff` 是**逐段裁决**的编辑器(每处修改单独接受/拒绝,合成结果实时可预览);
 *   本件是「整份 diff」的一次性操作面——展示同一份前后对照,但只有一个应用 / 拒绝 / 回退动作,
 *   适合 coding agent 产出补丁后「一并应用或放弃」的场景。
 * - `approval-card` 是**行动前审批**(风险档 + 批准/拒绝 + 决后收场);本件面向**已经产出**的
 *   文本变更,决定的是「这份修改要不要落到内容上」,不重复审批卡的风险与凭证语汇。
 *
 * - **不复制 diff 算法**:展示层直接复用 `inline-diff` 导出的纯函数 `diffTextSegments`
 *   (零依赖词级 LCS),本件只负责只读渲染与动作状态机。
 * - **状态机**:pending(可应用/拒绝)→ applying(onApply 返回 Promise,落定前双钮禁用)
 *   → applied(applied=true 显示「已应用」凭证 + 回退钮)。onReject / onRevert 都是纯回调,
 *   是否改变数据由消费方决定;本件不取数、不发请求(治理方案 §纯展示/受控件)。
 * - **a11y**:根 role="group" + aria-label;应用/已应用/只读等状态迁移经常驻 role="status"
 *   播报;动作钮为原生 button(可键盘聚焦)。删除/新增除颜色外还有 <del> 删除线、<ins>
 *   下划线两条附加通道。
 * - 文案缺省中文常量(§16),消费方经 labels 覆写接入 i18n。
 */
import { useMemo, useState } from 'react';
import { Check, RotateCcw } from 'lucide-react';
import { cn } from '@mox-hub/ui';
import { Button } from '@mox-hub/ui/components/button';
import { usePatternLabels } from '../lib/i18n';
import { diffTextSegments } from './inline-diff';

/** 文案覆写(缺省中文常量,§16;消费方经 labels 覆写接入 i18n) */
export interface ApplyDiffLabels {
  /** 容器可访问名(role="group" 的 aria-label) */
  containerLabel: string;
  /** 应用整份修改 */
  apply: string;
  /** 拒绝整份修改(回调由消费方处理) */
  reject: string;
  /** 已应用后回退(onRevert 存在时渲染) */
  revert: string;
  /** 已应用凭证 */
  applied: string;
  /** onApply Promise 落定前的进行中状态 */
  applying: string;
  /** 只读态说明(不渲染任何动作) */
  readOnly: string;
}

const DEFAULT_LABELS: ApplyDiffLabels = {
  containerLabel: 'AI 修改应用',
  apply: '应用修改',
  reject: '拒绝修改',
  revert: '回退',
  applied: '已应用',
  applying: '正在应用…',
  readOnly: '只读:仅展示修改内容',
};

export interface ApplyDiffProps {
  /** 原文(纯文本,\n 分段) */
  before: string;
  /** 修改后文本(纯文本,\n 分段) */
  after: string;
  /** 受控已应用态:true 显示「已应用」凭证并退出应用/拒绝动作 */
  applied?: boolean;
  /** 外部进行中态(如消费方正在提交其它请求):禁用动作并播报进行中 */
  busy?: boolean;
  /** 只展示 diff,不渲染任何动作钮(应用/拒绝/回退全部退出) */
  readOnly?: boolean;
  /** 应用回调;返回 Promise 时进入 busy 态,落定前应用/拒绝双钮禁用 */
  onApply: () => void | Promise<void>;
  /** 拒绝回调(可选;不传不渲染拒绝钮) */
  onReject?: () => void;
  /** 回退回调(可选;applied=true 且传入时渲染回退钮) */
  onRevert?: () => void;
  /** 文案覆写(缺省中文常量) */
  labels?: Partial<ApplyDiffLabels>;
  className?: string;
}

export function ApplyDiff({
  before,
  after,
  applied = false,
  busy = false,
  readOnly = false,
  onApply,
  onReject,
  onRevert,
  labels,
  className,
}: ApplyDiffProps) {
  const providerLabels = usePatternLabels('applyDiff', DEFAULT_LABELS);
  const l: ApplyDiffLabels = { ...providerLabels, ...labels };
  const segments = useMemo(() => diffTextSegments(before, after), [before, after]);
  const [pending, setPending] = useState(false);
  const busyState = busy || pending;

  const handleApply = () => {
    if (busyState) return;
    const result = onApply();
    if (result && typeof (result as Promise<void>).then === 'function') {
      // Promise 落定前禁双击;reject 视为未落定,恢复可操作(错误呈现归消费方)
      setPending(true);
      void (result as Promise<void>).then(
        () => setPending(false),
        () => setPending(false),
      );
    }
  };

  // applying / applied / readOnly 都是状态迁移:角色挂在对应的可见状态元素上(同 approval-card 约定),
  // 避免额外的 sr-only 副本造成同一句话在可访问树里出现两次。
  const actionClass = 'mt-3 flex flex-wrap items-center gap-2 border-t border-border/60 pt-3';

  return (
    <div
      data-slot="apply-diff"
      data-ai-component="apply-diff"
      data-state={readOnly ? 'readonly' : applied ? 'applied' : busyState ? 'applying' : 'pending'}
      role="group"
      aria-label={l.containerLabel}
      aria-busy={busyState || undefined}
      className={cn('rounded-lg border bg-card px-4 py-3', className)}
    >
      <div
        data-slot="apply-diff-body"
        className="whitespace-pre-wrap break-words text-sm leading-relaxed text-content-text"
      >
        {segments.map((segment) => {
          if (segment.type === 'unchanged') {
            return (
              <span key={segment.index} data-slot="apply-diff-segment" data-segment-type="unchanged">
                {segment.text}
              </span>
            );
          }
          return (
            <span
              key={segment.index}
              data-slot="apply-diff-segment"
              data-segment-type="changed"
              data-change-ordinal={segment.ordinal}
            >
              {segment.removed ? (
                // §8.5 第 4 条:删除不只靠颜色——<del> 删除线为附加通道
                <del className="rounded-xs bg-accent-red-light/70 px-0.5 text-accent-red line-through decoration-accent-red/60">
                  {segment.removed}
                </del>
              ) : null}
              {segment.added ? (
                // §8.5 第 4 条:新增不只靠颜色——<ins> 下划线为附加通道
                <ins
                  className={cn(
                    'rounded-xs bg-accent-green-light/70 px-0.5 text-accent-green underline decoration-accent-green/60',
                    segment.removed && 'ms-1',
                  )}
                >
                  {segment.added}
                </ins>
              ) : null}
            </span>
          );
        })}
      </div>

      {applied ? (
        // 已应用凭证:显示决定与回退出口;readOnly 时只留凭证,不渲染动作钮
        <div data-slot="apply-diff-receipt" className={cn(actionClass, 'justify-between')}>
          <span
            role="status"
            className="inline-flex items-center gap-1 text-xs font-medium text-accent-green"
          >
            <Check aria-hidden="true" className="size-3" />
            {l.applied}
          </span>
          {!readOnly && onRevert ? (
            <Button
              type="button"
              variant="ghost"
              size="xs"
              disabled={busyState}
              onClick={onRevert}
              data-ai-action="apply-diff.revert"
            >
              <RotateCcw aria-hidden="true" />
              {l.revert}
            </Button>
          ) : null}
        </div>
      ) : readOnly ? (
        <p
          role="status"
          data-slot="apply-diff-readonly"
          className={cn(actionClass, 'text-xs text-content-text-muted')}
        >
          {l.readOnly}
        </p>
      ) : (
        <div data-slot="apply-diff-actions" className={cn(actionClass, 'justify-end')}>
          {/* 卡片主操作统一右下:次要动作在前、主操作最右;进行中文案 me-auto 恒居左 */}
          {busyState ? (
            <span role="status" className="me-auto text-xs text-content-text-muted">
              {l.applying}
            </span>
          ) : null}
          {onReject ? (
            <Button
              type="button"
              variant="ghost"
              size="xs"
              disabled={busyState}
              onClick={onReject}
              data-ai-action="apply-diff.reject"
            >
              {l.reject}
            </Button>
          ) : null}
          <Button
            type="button"
            size="xs"
            disabled={busyState}
            onClick={handleApply}
            data-ai-action="apply-diff.apply"
          >
            {l.apply}
          </Button>
        </div>
      )}
    </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。

用法说明

AI 修改应用件:复用 inline-diff 展示,应用/拒绝/回退,Promise 提交态与已应用凭证;readOnly 只展示。