# ZSUI 0.3 输入体验路线图
## 目标
文本输入组件共享一致的提示、字段语义、输入法交互、辅助功能投影和三平台原生证据，
同时继续由应用持有真实值、校验结果和业务规则。公共 View 代码不选择平台，提示文字
不进入值、选择区、剪贴板、撤销栈或安全输入通道。
## 阶段一：Placeholder 语义统一
状态：实现就绪。
覆盖 `TextBox`、多行 `TextEditor`、`PasswordBox`、`NumberBox`、`AutoSuggestBox`、
`ComboBox` 与 `CommandPalette`。所有组件均可通过 `.placeholder(...)` 配置；
`command_palette_placeholder(...)` 作为兼容别名保留。
验收规则：
- 仅在真实文本或数值草稿为空时绘制提示；
- 使用平台主题的次要文字颜色，不在组件内定义私有颜色；
- 获得焦点后保留提示与真实插入光标，开始输入或 IME 预编辑时立即由真实内容替换；
- 提示不参与文本值、选择、删除、复制、撤销或提交；
- 空 PasswordBox 的提示只使用普通提示绘制命令，不创建或序列化安全文本；
- `UiDocument` 的 `textbox`、`password_box` 与 `number_box` 接受可本地化的
`placeholder` 字符串，并与 Rust View 使用同一运行时路径；
- 启用辅助功能时，基础文本输入将提示投影为帮助描述，实际值和控件角色保持独立。
## 阶段二：字段组合与校验呈现
引入可组合的输入字段语义，统一标签、必填标记、帮助文本、错误文本和校验状态。
应用继续拥有校验规则及错误内容；框架只负责类型化状态、布局、主题、焦点关联和辅助
功能关系。该阶段不引入全局表单注册表，也不在平台后端复制业务状态。
完成条件：
- Rust View 与 `UiDocument` 共享同一字段契约；
- 标签、帮助和错误节点拥有稳定 ID，并能关联到输入控件；
- 错误状态进入主题绘制和三平台辅助功能描述；
- 焦点、重建和热重载不会丢失兼容输入状态；
- 独立 Cargo feature 组合和无默认 feature 构建通过。
## 阶段三：三平台输入场景证据
把空值、获得焦点、普通输入、IME 预编辑/提交、清空、错误状态和安全输入加入统一
Native Proof 场景。在 Win32、AppKit 与 Linux Direct 的最终平台表面上验证截图、控件
边界、焦点、消息、输入法锚点和辅助功能描述。视觉基准只通过独立审查提交更新。
完成条件：
- 三平台运行同一份输入 Gallery 场景；
- 最终平台截图和版本化结构报告齐全；
- placeholder 不出现在提交值、剪贴板、PasswordBox 安全数据或动作日志中；
- UIA、NSAccessibility 与 AccessKit/AT-SPI 均能读取字段关系和提示描述；
- 固定 Runner 的语义、几何和视觉回归检查成为合并门禁。
## 阶段四：高级输入体验
在前述统一契约稳定后，继续实现本地化数值格式、NumberBox 空值范围辅助语义、
PasswordBox Caps Lock 提示、长建议列表滚动、搜索控件 active-descendant 语义，以及
真实中文输入法、VoiceOver、Narrator/NVDA 与 Orca 的发布前体验矩阵。自动协议证据与
真实辅助技术人工验收继续分开记录。
## 当前并行阶段：导航信息层
状态：已实现，待三平台目标证据。
`shell` 的导航行支持可选副文本（`description`，并提供 `subtitle` 别名），
副文本参与行高、绘制、裁剪和点击区域计算。
验收条件：
- Shell 的副文本和图标在 Win32、AppKit、Linux Direct 使用同一份
语义数据并完成最终平台截图；
- 副文本不改变稳定导航/会话 ID，行重排后点击仍返回原有 ID；
- 窄窗口下文本保留平台最小行高，图标和副文本不与徽章、滚动条重叠；
- 低并发构建通过 focused tests、全特性测试和锁定 feature matrix，目标运行时
内存采样保持在既有证明流程内。