AI审阅与决策
AutonomyDial
@mox-hub/patterns · AI · 审阅与决策 · canonical
autonomy-dial@mox-hub/patternsSemanticcanonicalsrc/components/autonomy-dial.tsx变体轴
sizesmmd
变体演示autonomy-dial
近期动作读取仓库文件(自己跑)提交 PR(先问我)删除生产数据(锁定必问)
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| value* | AutonomyLevel | — | — |
| onValueChange* | (level: AutonomyLevel) => void | — | — |
| samples* | AutonomySample[] | — | — |
| lockedLabel* | string | — | — |
| size* | "sm" | "md" | 'md' | — |
| disabled* | boolean | false | — |
| labels* | AutonomyDialLabels | — | — |
| className* | string | — | — |
源码
import { Lock } from 'lucide-react';
import { useRef } from 'react';
import type React from 'react';
import { RawButton } from '@mox-hub/ui/components/raw/raw-button';
import { cn } from '@mox-hub/ui';
import { useDirection } from '@mox-hub/ui/i18n';
import { usePatternLabels } from '../lib/i18n';
/**
* AutonomyDial - [AI] 自治边界拨盘(组件规划账本 B5,需求卡 B-07 三级分级授权)。
*
* 回答「哪些动作它可以自己跑、哪些必先问我」的运行时边界操作 UI:三档段选拨盘——
* 锁定必问(locked)/ 先问我(ask)/ 自己跑(auto),从严到宽左→右排列;
* locked 档带 lucide Lock 锁形标识(§6.1)。视觉语言对齐 ui/segmented-control
* 的 pill 滑块(rect 变体):滑块 translateX 归位表达「档位间滑动」。
*
* **数据契约(真实形状,不造配置模型)**:B-07 授权配置的唯一持久化形状是
* `Member.trustLevel`(1=观察者 / 2=协助者 / 3=受托者,`PATCH /members/:id` 写入,
* server trust.service 只认三级数值)。本件是通用语义件,value 走自治语义词表
* `AutonomyLevel`;真实档位 ↔ 自治档位的映射(受托者=auto / 协助者=ask /
* 观察者=locked,1:1 无损)由消费方持有——领域词表不进语义层。
*
* **样例滑轨**:samples(该成员近期真实动作 + 落档)存在时在拨盘下方一行小字展示
* 「它的真实行为分布」——色点表档位 + sr-only 档位名兜底(§8.5#4 不只靠颜色),
* 纯展示不可点(无 button 语义、零交互)。
*
* **受控约定**:value 必受控(本件是授权配置入口,不持有态;§10.7「受控须同时
* 支持非受控」在本件被任务裁决豁免——配置入口做非受控会出现「界面已切档、持久化
* 未跟」的双真相)。禁在组件内部 useState 缓存传入值(§10.7)。
*
* **a11y(§8.5)**:`role="radiogroup"` + 三 `role="radio"` + `aria-checked`;
* roving tabindex(选中档 tabIndex=0,其余 -1)+ 方向键 / Home / End 切档
* (焦点随选择移动,APG radiogroup 模式;与 ui/stepper 同款手办——role=radio 的
* button 不自然获得原生方向键行为,须手动实现)。disabled 时各档 aria-disabled、
* 原生 disabled 兜底、整件退出键盘流。焦点可见走 `focus-visible:ring-ring`(§8.1)。
*
* 原语通道:段位是「非动作钮」(radio 语义把手),经 RawButton(原语层出口,
* 语义件既定通道)渲染;...props 透传根元素(§10.7);文案中文常量 + labels 覆写
* (§16)。
*/
/** 自治档位:locked=锁定必问 / ask=先问我 / auto=自己跑(拨盘从左到右由严到宽) */
export type AutonomyLevel = 'locked' | 'ask' | 'auto';
/** 样例:该成员近期一条真实动作 + 它落在的档位(展示「真实行为分布」,不可点) */
export interface AutonomySample {
label: string;
level: AutonomyLevel;
}
/** 单档文案覆写:label=档名、desc=一句人话说明 */
export interface AutonomyLevelLabels {
label?: string;
desc?: string;
}
export interface AutonomyDialLabels {
/** 读屏组名(radiogroup 可访问名),默认「自治边界」 */
group?: string;
/** 样例滑轨前缀标题,默认「近期动作」 */
samples?: string;
locked?: AutonomyLevelLabels;
ask?: AutonomyLevelLabels;
auto?: AutonomyLevelLabels;
}
export interface AutonomyDialProps extends React.ComponentProps<'div'> {
/** 当前档位(必受控:本件是授权配置入口,不持有态) */
value: AutonomyLevel;
/** 切档回调(点击 / 方向键 / Home / End 均走此处) */
onValueChange: (level: AutonomyLevel) => void;
/** 该成员近期真实动作样例(可选);缺席则不渲染样例滑轨 */
samples?: AutonomySample[];
/** 锁定档说明(为什么锁定);仅在当前档为 locked 时显示 */
lockedLabel?: string;
/** 尺寸档:sm=对话框/卡片内 / md=面板默认 */
size?: 'sm' | 'md';
/** 整件禁用(各档 aria-disabled + 原生 disabled,退出键盘流) */
disabled?: boolean;
/** 文案覆写(§16:默认中文常量,消费方可覆写为 i18n 词条) */
labels?: AutonomyDialLabels;
className?: string;
}
/** 拨盘档序:从左到右由严到宽(锁定必问 → 先问我 → 自己跑) */
const LEVEL_ORDER: readonly AutonomyLevel[] = ['locked', 'ask', 'auto'];
/** 默认文案(§16 中文常量;labels 逐档覆写) */
const DEFAULT_LEVEL_LABELS: Record<AutonomyLevel, Required<AutonomyLevelLabels>> = {
locked: { label: '锁定必问', desc: '一切动作先问,不可自助' },
ask: { label: '先问我', desc: '每步先给你确认' },
auto: { label: '自己跑', desc: '按它的信任等级直接执行' },
};
/** 档位语义色(§5.3 分类语义):locked=黄(谨慎)/ ask=蓝(常规)/ auto=绿(受托),
* 与 TrustLevelBadge 三级配色同源(观察者黄 / 协助者蓝 / 受托者绿) */
const LEVEL_TONE: Record<AutonomyLevel, { slider: string; text: string; dot: string }> = {
locked: {
slider: 'border-accent-yellow/50 bg-accent-yellow-light',
text: 'text-accent-yellow',
dot: 'bg-accent-yellow',
},
ask: {
slider: 'border-accent-blue/40 bg-accent-blue-light',
text: 'text-accent-blue',
dot: 'bg-accent-blue',
},
auto: {
slider: 'border-accent-green/40 bg-accent-green-light',
text: 'text-accent-green',
dot: 'bg-accent-green',
},
};
/** 尺寸档:字号与图标 px 软配对(§6.2:text-xs 配 14px / text-2xs 配 12px) */
const SIZE_CLASS: Record<NonNullable<AutonomyDialProps['size']>, {
label: string;
desc: string;
icon: string;
}> = {
sm: { label: 'text-xs', desc: 'text-2xs', icon: 'size-3' },
md: { label: 'text-sm', desc: 'text-xs', icon: 'size-3.5' },
};
export function AutonomyDial({
value,
onValueChange,
samples,
lockedLabel,
size = 'md',
disabled = false,
labels,
className,
...rest
}: AutonomyDialProps) {
const direction = useDirection();
const isRtl = direction === 'rtl';
const segmentRefs = useRef(new Map<AutonomyLevel, HTMLButtonElement>());
// 未知值防御:钳到最严档(locked),不渲染幽灵选中态
const activeIndex = Math.max(0, LEVEL_ORDER.indexOf(value));
const activeTone = LEVEL_TONE[LEVEL_ORDER[activeIndex]];
const sizeClass = SIZE_CLASS[size];
const defaults = usePatternLabels('autonomyDial', DEFAULT_LEVEL_LABELS);
const levelText = (level: AutonomyLevel): Required<AutonomyLevelLabels> => ({
...defaults[level],
...labels?.[level],
});
/** APG radiogroup:方向键 / Home / End 切档,焦点随选择移动 */
const moveTo = (index: number) => {
const next = Math.min(Math.max(index, 0), LEVEL_ORDER.length - 1);
onValueChange(LEVEL_ORDER[next]);
segmentRefs.current.get(LEVEL_ORDER[next])?.focus();
};
const handleKeyDown = (event: React.KeyboardEvent<HTMLDivElement>) => {
if (disabled) return;
const currentIndex = LEVEL_ORDER.indexOf(value);
switch (event.key) {
case 'ArrowRight':
event.preventDefault();
moveTo(currentIndex + (isRtl ? -1 : 1));
break;
case 'ArrowLeft':
event.preventDefault();
moveTo(currentIndex + (isRtl ? 1 : -1));
break;
case 'ArrowDown':
event.preventDefault();
moveTo(currentIndex + 1);
break;
case 'ArrowUp':
event.preventDefault();
moveTo(currentIndex - 1);
break;
case 'Home':
event.preventDefault();
moveTo(0);
break;
case 'End':
event.preventDefault();
moveTo(LEVEL_ORDER.length - 1);
break;
}
};
return (
<div
data-slot="autonomy-dial"
data-ai-component="autonomy-dial"
data-value={value}
{...rest}
role="radiogroup"
aria-label={labels?.group ?? '自治边界'}
aria-disabled={disabled || undefined}
onKeyDown={(event) => {
handleKeyDown(event);
rest.onKeyDown?.(event);
}}
className={cn('w-full', className)}
>
{/* 滑块轨道:视觉语言对齐 segmented-control rect 变体(inset 半格 + tone 滑块) */}
<div className="relative grid w-full grid-cols-3 overflow-hidden rounded-lg border border-border bg-muted/50 p-0.5">
<span
aria-hidden="true"
data-slot="autonomy-dial-slider"
className={cn(
'pointer-events-none absolute inset-y-0.5 start-0.5 rounded-sm border bg-muted/50 shadow-xs transition-transform duration-slow ease-out',
activeTone.slider,
)}
style={{
width: 'calc((100% - 4px) / 3)',
transform: `translateX(calc(${isRtl ? -activeIndex : activeIndex} * 100%))`,
}}
/>
{LEVEL_ORDER.map((level) => {
const text = levelText(level);
return (
<RawButton
key={level}
ref={(el) => {
if (el) segmentRefs.current.set(level, el);
else segmentRefs.current.delete(level);
}}
role="radio"
aria-checked={value === level}
aria-disabled={disabled || undefined}
disabled={disabled}
tabIndex={disabled ? -1 : value === level ? 0 : -1}
onClick={() => onValueChange(level)}
data-slot="autonomy-dial-option"
data-level={level}
className={cn(
'relative z-sticky flex flex-col items-center gap-0.5 rounded-sm px-2 py-1.5 text-center outline-none transition-colors focus-visible:ring-2 focus-visible:ring-ring/50',
value === level
? activeTone.text
: 'text-muted-foreground hover:text-foreground',
)}
>
<span className={cn('inline-flex items-center gap-1 font-medium', sizeClass.label)}>
{level === 'locked' ? (
<Lock data-slot="autonomy-dial-lock" aria-hidden="true" className={sizeClass.icon} />
) : null}
{text.label}
</span>
<span className={cn('leading-snug', sizeClass.desc)}>{text.desc}</span>
</RawButton>
);
})}
</div>
{/* 锁定档说明(为什么锁定):仅当前档为 locked 时出现 */}
{value === 'locked' && lockedLabel ? (
<p
data-slot="autonomy-dial-locked-note"
className="mt-1.5 flex items-start gap-1 text-2xs leading-snug text-muted-foreground"
>
<Lock aria-hidden="true" className="mt-0.5 size-3 shrink-0" />
{lockedLabel}
</p>
) : null}
{/* 样例滑轨:近期真实动作落在哪档(色点 + sr-only 档名兜底 §8.5#4);仅展示不可点 */}
{samples?.length ? (
<div
data-slot="autonomy-dial-samples"
className="mt-1.5 flex flex-wrap items-center gap-x-3 gap-y-1"
>
<span className="text-2xs text-muted-foreground">{labels?.samples ?? '近期动作'}</span>
{samples.map((sample, index) => (
<span
key={`${sample.label}-${index}`}
title={`${sample.label}(${levelText(sample.level).label})`}
className="inline-flex items-center gap-1 text-2xs text-muted-foreground"
>
<span
aria-hidden="true"
className={cn('size-1.5 shrink-0 rounded-full', LEVEL_TONE[sample.level].dot)}
/>
{sample.label}
<span className="sr-only">({levelText(sample.level).label})</span>
</span>
))}
</div>
) : null}
</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。
用法说明
自治边界三档选择:locked/ask/auto 必受控;三档即三态,aria-checked 承载 selected;locked 档必须给 lockedLabel 说明原因。