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* | boolean | false | — |
| busy* | boolean | false | — |
| readOnly* | boolean | false | — |
| onApply* | () => void | Promise<void> | — | — |
| onReject* | () => void | — | — |
| onRevert* | () => void | — | — |
| labels* | Partial<ApplyDiffLabels> | — | — |
| className* | string | — | — |
源码
/**
* 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/translatorprops,其次用I18nProvider目录;内置 zh-CN 默认值,en-US 为参考翻译。见Theming · i18n 与 RTL。 - 对比度:高对比度 token、2px 控件边框与 3px 焦点环由主题层统一提供,见Foundations · Contrast。
用法说明
AI 修改应用件:复用 inline-diff 展示,应用/拒绝/回退,Promise 提交态与已应用凭证;readOnly 只展示。