PatternsSemantic
PathInput
@mox-hub/patterns 模式 · Semantic · canonical
path-input@mox-hub/patternsSemanticcanonicalsrc/components/path-input.tsx变体演示path-input
AI 同事执行文件操作的根目录
Props API
| Prop | 类型 | 默认值 | 说明 |
|---|---|---|---|
| value* | string | — | — |
| onChange* | (next: string) => void | — | — |
| kind* | "directory" | "file" | 'directory' | — |
| label* | ReactNode | — | — |
| description* | ReactNode | — | — |
| placeholder* | string | — | — |
| id* | string | — | — |
| loading* | boolean | false | — |
| disabled* | boolean | false | — |
| pickerTitle* | string | — | — |
| pickerFilters* | { name: string; extensions: string[]; }[] | — | — |
| onValidate* | (path: string) => Promise<PathCheckResult> | — | — |
| onCreate* | (path: string) => Promise<PathCheckResult> | — | — |
| savedStatus* | "valid" | "invalid" | "unknown" | null | — |
| savedValidatedAt* | string | null | — |
| inputClassName* | string | — | — |
| pick* | (request: PathPickRequest) => Promise<string> | — | — |
| translate* | PatternTranslate | — | — |
源码
/**
* PathInput - 路径输入语义组件(CAP-A-28,2026-10-03)
*
* 全仓路径录入统一件:手输 + 桌面壳系统选择器(choose_directory / choose_file)
* + 后端实测验证(onValidate)+ 失效一键创建(onCreate,仅目录且结果 missing 时出现)
* + 全失败路径保底报错(动作抛错原样呈现,绝不静默)。
* 验证结论一律来自后端(props 注入),组件不做路径格式臆断拦截;
* 纯 web 无壳时选择器入口隐藏、手输全通——选择器是加速项不是唯一入口。
* 与 SettingsFieldRow 的分工:本件是路径专用字段(自带选择器/验证/创建),
* 不是通用「左说明右控件」行骨架;勿混用。
* props 面封闭:不接 className、不透传样式(inputClassName 仅输入框内文体,如等宽)。
*/
import { useState } from 'react';
import { FolderOpen } from 'lucide-react';
import { Badge } from '@mox-hub/ui/components/badge';
import { Button } from '@mox-hub/ui/components/button';
import { Input } from '@mox-hub/ui/components/input';
import { Label } from '@mox-hub/ui/components/label';
import { Spinner } from '@mox-hub/ui/components/spinner';
import { type PatternTranslate } from '../lib/translate';
import { usePatternTranslate } from '../lib/i18n';
import { useFormatters } from '@mox-hub/ui/i18n';
/** 系统选择器请求:库内不直连桌面壳桥,由消费方注入 pick 实现。 */
export interface PathPickRequest {
kind: 'directory' | 'file';
title?: string;
filters?: { name: string; extensions: string[] }[];
}
const PATH_INPUT_LABELS: Record<string, string> = {
'path-input.pickFile': '选择文件…',
'path-input.pickDirectory': '选择目录…',
'path-input.status.unknown': '未验证',
'path-input.status.checking': '验证中…',
'path-input.status.creating': '创建中…',
'path-input.status.valid': '路径有效',
'path-input.status.invalid': '无效',
'path-input.savedAt': '已于 {{time}} 验证',
'path-input.actionFailed': '操作失败:{{message}}',
'path-input.action.validate': '验证',
'path-input.action.create': '创建目录',
};
/** 后端实测校验结果(与 WorkspaceValidationResult 同形,机器字段 missing 驱动创建动作) */
export interface PathCheckResult {
status: 'valid' | 'invalid' | 'unknown';
error?: string;
suggestion?: string;
gitRepoDetected?: boolean;
/** 路径不存在——onCreate 在场时出现「创建目录」动作 */
missing?: boolean;
}
export interface PathInputProps {
/** 受控值(绝对路径) */
value: string;
onChange: (next: string) => void;
/** 选择器种类:目录(默认)或单文件 */
kind?: 'directory' | 'file';
/** 字段标签 */
label?: React.ReactNode;
/** helper 说明 */
description?: React.ReactNode;
placeholder?: string;
/** 输入框 id(表单关联/测试锚点) */
id?: string;
/** 远端配置加载中——输入与全部动作禁用 */
loading?: boolean;
disabled?: boolean;
/** 系统选择器窗口标题;缺省按 kind 取组件文案 */
pickerTitle?: string;
/** 单文件选择器扩展名过滤(仅 Windows 有意义,按平台条件传入) */
pickerFilters?: { name: string; extensions: string[] }[];
/** 后端验证(入参 = 输入框当前值);不传则无验证钮与状态徽标 */
onValidate?: (path: string) => Promise<PathCheckResult>;
/** 失效建目录(仅 kind='directory' 且验证结果 missing 时出现在动作区) */
onCreate?: (path: string) => Promise<PathCheckResult>;
/** 已存记录的验证回显(来自 DB,如 workspace.validationStatus)——无即时结果时展示 */
savedStatus?: 'valid' | 'invalid' | 'unknown' | null;
savedValidatedAt?: string | null;
/** 输入框文体(等宽等);仅作用于输入框 */
inputClassName?: string;
/** 系统选择器入口;不传则隐藏选择按钮(纯 web / 库消费方默认无壳桥)。 */
pick?: (request: PathPickRequest) => Promise<string | null>;
/** 文案覆写(默认 zh-CN;主仓 i18n 适配层集中传入 t() 包装)。 */
translate?: PatternTranslate;
}
type Phase = 'idle' | 'checking' | 'creating';
export function PathInput({
value,
onChange,
kind = 'directory',
label,
description,
placeholder,
id,
loading = false,
disabled = false,
pickerTitle,
pickerFilters,
onValidate,
onCreate,
savedStatus = null,
savedValidatedAt = null,
inputClassName,
pick,
translate,
}: PathInputProps) {
const providerT = usePatternTranslate('pathInput', PATH_INPUT_LABELS);
const F = useFormatters();
const t = translate ?? providerT;
const [check, setCheck] = useState<PathCheckResult | null>(null);
const [phase, setPhase] = useState<Phase>('idle');
const [actionError, setActionError] = useState<string | null>(null);
const canPick = Boolean(pick);
const busy = phase !== 'idle';
const allDisabled = disabled || loading;
const resetResult = () => {
setCheck(null);
setActionError(null);
};
const handlePick = async () => {
if (!pick) return;
try {
const path = await pick({
kind,
title:
pickerTitle ??
(kind === 'file'
? t('path-input.pickFile')
: t('path-input.pickDirectory')),
filters: pickerFilters,
});
if (path) {
resetResult();
onChange(path);
}
} catch {
// 选择器失败静默回落手输——选择器是加速项不是唯一入口
}
};
const runAction = async (phaseName: Phase, action: (p: string) => Promise<PathCheckResult>) => {
if (!value.trim()) return;
setPhase(phaseName);
setActionError(null);
try {
setCheck(await action(value.trim()));
} catch (err) {
setCheck(null);
setActionError(err instanceof Error ? err.message : String(err));
} finally {
setPhase('idle');
}
};
// 状态展示优先级:进行中 > 即时验证结果 > 已存回显 > 未验证(无验证能力时整行省略)
const showCreate =
kind === 'directory' && !!onCreate && check?.missing === true;
let statusVariant: 'secondary' | 'destructive' | 'outline' = 'outline';
let statusLabel: string = t('path-input.status.unknown');
if (phase === 'checking') {
statusLabel = t('path-input.status.checking');
} else if (phase === 'creating') {
statusLabel = t('path-input.status.creating');
} else if (check) {
if (check.status === 'valid') {
statusVariant = 'secondary';
statusLabel = t('path-input.status.valid');
} else {
statusVariant = 'destructive';
statusLabel = t('path-input.status.invalid');
}
} else if (savedStatus) {
if (savedStatus === 'valid') {
statusVariant = 'secondary';
statusLabel = t('path-input.status.valid');
} else if (savedStatus === 'invalid') {
statusVariant = 'destructive';
statusLabel = t('path-input.status.invalid');
}
}
const showStatusRow = busy || !!check || !!savedStatus;
return (
<div data-slot="path-input" className="space-y-1.5">
{label ? (
<Label htmlFor={id}>{label}</Label>
) : null}
<div className="flex gap-2">
<Input
id={id}
value={value}
onChange={(e) => {
resetResult();
onChange(e.target.value);
}}
placeholder={placeholder}
disabled={allDisabled}
className={inputClassName}
/>
{canPick ? (
<Button
type="button"
variant="outline"
size="icon"
onClick={handlePick}
disabled={allDisabled}
title={pickerTitle ?? (kind === 'file' ? t('path-input.pickFile') : t('path-input.pickDirectory'))}
aria-label={
pickerTitle ?? (kind === 'file' ? t('path-input.pickFile') : t('path-input.pickDirectory'))
}
>
<FolderOpen className="size-4" />
</Button>
) : null}
</div>
{description ? (
<p className="text-xs text-muted-foreground">{description}</p>
) : null}
{showStatusRow ? (
<div className="flex items-center gap-2">
<Badge variant={statusVariant}>
{busy ? <Spinner size="sm" /> : null}
{statusLabel}
</Badge>
{!check && !busy && savedValidatedAt ? (
<span className="text-xs text-muted-foreground">
{t('path-input.savedAt', {
time: F.dateTime(savedValidatedAt),
})}
</span>
) : null}
</div>
) : null}
{check?.status === 'invalid' && (check.error || check.suggestion) ? (
<div className="rounded-md border border-destructive/40 bg-destructive/10 px-3 py-2">
{check.error ? (
<p className="text-xs text-destructive">{check.error}</p>
) : null}
{check.suggestion ? (
<p className="mt-0.5 text-xs text-muted-foreground">{check.suggestion}</p>
) : null}
</div>
) : null}
{actionError ? (
<p className="text-xs text-destructive" role="alert">
{t('path-input.actionFailed', { message: actionError })}
</p>
) : null}
{onValidate || showCreate ? (
<div className="flex gap-2">
{onValidate ? (
<Button
type="button"
variant="outline"
size="xs"
onClick={() => runAction('checking', onValidate)}
disabled={allDisabled || busy || !value.trim()}
>
{t('path-input.action.validate')}
</Button>
) : null}
{showCreate ? (
<Button
type="button"
variant="secondary"
size="xs"
onClick={() => (onCreate ? runAction('creating', onCreate) : undefined)}
disabled={allDisabled || busy || !value.trim()}
>
{t('path-input.action.create')}
</Button>
) : null}
</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。
用法说明
路径录入统一件:手输 + 可选 pick 选择器 + onValidate/onCreate 后端结果注入;库内不直连桌面壳桥,translate 注入文案。