Field 组件契约¶
契约概览¶
| 区域 | 契约 |
|---|---|
| 公开契约 | Field 用一个标签、可选描述和状态、可选性指示符、显式宽度以及根 BaseProps 包裹调用方拥有的控件;它还消费 FormLayout 的水平标签模式。 |
| 行为 | 单个控件使用原生标签关联;分组使用带标签的 span。状态消息获得稳定 ID 并使用持久化的实时区域。水平标签模式暴露一个受保护的 data-layout 主题轴。 |
| 终端用户影响 | 用户可以识别自定义控件、听到其描述和变化的状态,并在普通和水平表单布局中保持标签/控件/状态之间的关系。 |
| 构建者影响 | 构建者提供控件及其 ID,将描述/状态 ID 关联到该控件,在需要时选择分组语义,并使用对包裹表面安全的状态放置方式。 |
| 兼容性/就绪状态 | 记录已发布行为;无 API、默认值或 DOM 变更。任意子元素的默认 statusVariant="attached" 与 family:input-fields/FR8 冲突;列在“当前状态影响”下,迁移保持开放(OQ1)。 |
| 审查检查 | 拒绝丢失的标签/分组关联、被丢弃的根 props、调用方替换 data-layout、重复/缺失的状态播报、逃逸的局部 z-index、未文档化的公开字面量,或声称所有自定义控件都安全支持 attached 状态的声明。 |
| 治理规则 | 已确立的公开 Field 接口;family:input-fields 共享所有权和 FR8;architecture:public-component-api/INV5–INV8;spec:AST-027/FR1–FR3;HTML label 和 ARIA 命名/描述语义。 |
此表为审查投影;下文正文具有权威性。
意图¶
Field 为尚未拥有 Astryx 字段外壳的原生、自定义或第三方控件提供共享的标签、描述、状态、宽度和布局装饰。调用方继续拥有控件的值、交互模型和控件特定的无障碍语义。
兼容性与迁移¶
- 已发布默认值保持不变:是;
statusVariant在当前实现中仍默认为attached。 - 兼容性类别:记录已发布行为;无公开 prop、默认值、导出或 DOM 变更。
- 受控/非受控行为:由调用方拥有且保持不变。
- 迁移决策:无;解决 OQ1 需要单独的兼容性决策。
所有权边界¶
拥有
- 根字段盒、显式宽度、局部层叠边界和组合顺序。
- 围绕调用方控件的标签和描述放置。
- 单控件与分组标签语义。
- 状态消息放置和持久化实时区域播报。
- FormLayout 水平标签投影。
不拥有 / 非目标
- 被包裹控件的值、焦点模型、键盘行为、禁用行为或事件语义——由调用方或被包裹组件拥有。
- 将
aria-describedby应用于被包裹控件——调用方提供控件并关联生成或显式的 ID。 FieldLabel、FieldStatus、Tooltip或调用方拥有的子元素的视觉和语义契约——由这些组件拥有。- 输入族成员 API 和控件盒 part props——由
family:input-fields和每个成员拥有。
公开概念¶
| 概念 | 封闭值或状态 | 含义 | 按变体/方向/状态的可用性 | 默认值 | 所有者 | 稳定性 | 无效值行为 |
|---|---|---|---|---|---|---|---|
| 标签模式 | 单控件;分组 | 选择原生的 <label htmlFor> 或通过 aria-labelledby 命名的 <span>。 |
所有布局。 | 单控件 | component:Field |
已发布 | 类型约束 |
| 标签可见性 | 可见;视觉隐藏 | 在视觉上隐藏标签和描述,同时为辅助技术保留它们。 | 所有布局。 | 可见 | component:Field |
已发布 | 类型约束 |
| 可选性标记 | 无;可选;必填 | 显示 FormLayout 可选性默认值的本地化例外。 | 标签呈现方式。 | 无 | component:Field |
已发布 | 两者同时设置时发出警告;可选状态在视觉上优先,除非 FormLayout 的默认值为可选,此时会隐藏可选状态并显示必填状态。 |
| 状态放置 | attached;detached;tooltip |
将状态框放置在控件后方、下方,或保留可见的 tooltip 提示以指向输入。 | 渲染状态框需要消息;tooltip 仍会播报消息。 | attached(见 OQ1) |
family:input-fields |
已发布;存在一致性差距 | 受类型约束 |
| 宽度 | 无;数字;CSS 尺寸字符串 | 设置完整普通字段框的尺寸。 | 普通框布局;水平标签模式使用 display: contents。 |
所属布局 | component:Field |
已发布 | 受类型约束 |
| 字段布局 | 普通框;来自 FormLayout 的 horizontal-labels |
将内容堆叠,或将标签和输入组投射到父级网格中。 | 从 FormLayoutContext 解析。 |
普通框 | component:Field |
已发布 | 受上下文约束 |
| 描述/状态 ID | 显式;根据 inputID 生成;无 |
为调用方拥有的 aria-describedby 连接提供稳定的描述和消息元素名称。 |
仅当相应文本存在时生成。 | 存在文本时生成 | component:Field |
已发布 | 空文本会省略输出 |
行为与布局契约¶
| ID | 不变式 | 依据 |
|---|---|---|
| FR1 | 单控件标签渲染为 <label htmlFor={inputID}>;组标签渲染为带有 labelID 的非标签元素,供调用方拥有的 aria-labelledby 使用。 |
已确立的公共接口;HTML 和 ARIA 语义 |
| FR2 | 视觉隐藏的标签和描述保留在 DOM 中,且不参与布局流。 | 已确立的公共接口和可访问性行为 |
| FR3 | 描述和状态 ID 在显式提供时使用显式值;否则仅在文本存在时解析为 ${inputID}-desc 和 ${inputID}-status。 |
已确立的公共接口 |
| FR4 | 错误状态消息通过持久化实时区域以断言方式播报,警告/成功消息以礼貌方式播报;tooltip 放置不渲染 FieldStatus 框,但保留播报。 |
现有测试;组件族职责 |
| FR5 | 普通布局按标签、控件、可选状态的顺序排列。水平标签模式将标签包装器放在一个描述/控件/状态组之前,并体现 data-layout="horizontal-labels";调用方 props 不能替换该所属主题标记。 |
已确立的布局接口;architecture:public-component-api/INV5 |
| FR6 | width 应用于普通根字段框;它不会为调用方拥有的控件设置样式,且在水平标签模式下没有可作用的目标框。 |
已确立的公共接口;family:input-fields 共享所属者 |
| FR7 | 根引用、data/ARIA/DOM 输入、事件、xstyle、类名和内联样式都到达或组合在根上,而不会替换组件所属的语义。 |
architecture:public-component-api/INV5–INV8 |
| FR8 | Field 根元素隔离每个本地附加状态绘制关系,而不为根元素分配页面级 z-index。 | spec:AST-027/FR1–FR3, FR11 |
| FR9 | Field MUST 仅将附加放置给予不透明、有边框、固定高度且尺寸反映可靠的控件;对于过高、换行、半透明、无边框或其他不合格的控件(自定义控件通常如此),应使用分离式或组件所属的放置。实现差距:statusVariant 对每个子项默认取 attached,因此除非调用方另行选择,否则不合格控件会获得附加放置 (OQ1)。 |
family:input-fields/FR8 |
允许的变体¶
- AV1 — 调用方拥有的控件。 任何控件标记都可以占据该插槽;Field 不会检查、克隆或更改它。
- AV2 — 表单排列。 FormLayout 可以选择普通排列或水平标签排列,而无需更改标签、描述、状态或公告的所属关系。
- AV3 — 状态表面。 符合条件的控件可以使用附加放置;其他控件使用分离式或成员拥有的工具提示呈现。
代表性状态¶
| 状态 | 必需不变量 | 允许的变体 |
|---|---|---|
| 仅标签 | 一个关联标签位于调用方拥有的控件之前。 | 可见或视觉隐藏。 |
| 描述 | 一个描述元素接收解析后的 ID。 | 调用方可以使用显式 ID 或生成的值。 |
| 组 | 组标签不是字面 <label>,并且可通过 ID 引用。 |
调用方拥有组角色和 aria-labelledby。 |
| 状态 | 消息接收解析后的 ID,并在其紧急通道上播报一次。 | 附加/分离式框或工具提示拥有的可见提示。 |
| 水平标签 | 标签和输入组参与父级网格并保留 data-layout。 |
描述/状态可以不存在。 |
| 显式宽度 | 普通根元素接收请求的大小并保持可收缩。 | 数字或 CSS 尺寸字符串。 |
转换与优先级顺序¶
- ORD1 — 根 props。 调用方的 DOM/data/event props 首先转发;随后应用 Field 拥有的视觉状态反射;StyleX、调用方类名和调用方内联样式按文档记录的顺序组合。
- ORD2 — ID。 显式描述/状态 ID 优先;否则,文本存在时从
inputID派生 ID;文本不存在时不生成带 ID 的元素。 - ORD3 — 可选项。 FormLayout 的默认可选项会抑制匹配的可见标记;如果两个局部布尔值都为 true,Field 会发出警告,并且可选标记在可见性上获胜,除非 FormLayout 的默认值为 optional,此时会抑制它,以便显示必填标记。
性能与资源¶
- PR1 — 无字段级全局资源。 Field 不拥有监听器、观察器、定时器或外部存储。状态播报委托给共享的持久实时区域运行时,
labelTooltip引入共享 Tooltip 的监听器和层。
无障碍契约¶
- AR1 — 标签关联。 单一控件获得原生标签关联;分组控件使用由调用方接线的
aria-labelledby,绝不使用会误导的字面<label>。 - AR2 — 描述关联。 描述文本与可访问名称保持分离,并暴露一个稳定 ID,供调用方拥有的
aria-describedby使用。 - AR3 — 状态播报。 变化中的状态文本通过持久实时区域播报,包括在未渲染消息框时通过 tooltip 放置位置播报。
- AR4 — 隐藏标签。 视觉上隐藏的标签和描述文本仍可供辅助技术使用。
设计关系¶
当前仓库中没有设计记录约束组件局部的视觉调优。 标签、描述和状态使用共享的语义化类型、颜色和间距令牌。
主题化结构¶
{
"Container": {"target": "field"},
"Label": {"target": "field-label"},
"Ordinary description": {
"none": {
"reason": "reachability-gap: The ordinary-layout description paints supporting text outside the field-label target and has no current public target of its own."
}
},
"Horizontal-label description": {
"delegatesTo": {"owner": "component:Text", "target": "text"}
},
"Control slot": {
"none": {
"reason": "intentional: The wrapped control is caller-owned or another Astryx component and retains its own theming surface."
}
},
"Status message": {"target": "field-status"},
"Input status icon": {"target": "input-status-icon"},
"Input clear button": {"target": "input-clear-button"},
"Input clear icon": {"target": "input-clear-icon"},
"Optional/Required indicator": {"inherits": "field-label"},
"Label tooltip trigger": {
"none": {
"reason": "unsettled: the trigger is component:InfoTip's button, which has no public theming target yet; its info icon stays on Icon/icon through InfoTip"
}
},
"Label tooltip surface": {
"delegatesTo": {"owner": "component:Tooltip", "target": "tooltip"}
}
}
普通描述保持稳定的消费方结构,不包含 Field 拥有的目标。可见的水平标签描述委托给 Text/text;当 isLabelHidden 为 true 时,相同内容委托给 VisuallyHidden,且不暴露任何可绘制目标。标签 tooltip 将其 component:InfoTip 触发按钮(尚无公开目标)与其由层承载的 Tooltip/tooltip 表面分离。
家族与系统关系¶
family:input-fields拥有共享的状态放置能力,并将 Field 标识为独立标签、描述、状态放置和显式宽度的所有者。architecture:public-component-api拥有根级 prop、样式、事件和 ref 组合。architecture:component-theming-surface拥有结构限定与目标处置。architecture:component-test-sufficiency拥有突变敏感的证据和有界划分。spec:AST-027拥有控件与其附属状态之间隔离的局部绘制关系。
验证映射¶
| 契约 | 验证 | 代表性状态 | 变异或失败预期 | 审计章节 |
|---|---|---|---|---|
| FR1–FR3, ORD2, AR1, AR2, AR4 | Field.test.tsx 的标签元素、分组标签、隐藏标签与描述、描述 ID 和生成 ID 用例 |
单一控件、分组、可见和隐藏标签、显式与生成的 ID | 关联丢失、元素错误、隐藏文本缺失或 ID 错误则失败。 | audit:Field/accessibility |
| FR4, AR3 | Field.test.tsx 的播报与 tooltip 放置用例 |
首次挂载、更新、重复、错误、警告、tooltip、无消息 | 缺失、重复、过期或紧急程度错误的播报则失败。 | audit:Field/accessibility |
| FR5, FR6, ORD1 | Field.test.tsx 的水平标签、宽度和窄行用例 |
普通与水平布局;字符串和数字宽度;窄行 | 可替换的布局标记、错误的网格分组或内层控件上的宽度则失败。证据缺口:没有测试断言普通布局下的标签、控件、状态顺序。 | audit:Field/layout |
| FR7 | Field.test.tsx 的 ref 与水平标签根级 prop 用例 |
ref;水平模式下的 class、style、data 和事件 prop | ref 丢失或调用方替换的布局标记则失败。证据缺口:没有测试断言普通布局下的根级 xstyle、class、style 和事件 prop。 |
audit:Field/api |
| ORD3 | Field.test.tsx 中的 optional、required 及两者均设置(both-set)用例;FormLayout.test.tsx 中经由 Field 的默认可选性用例 |
可选;必填;两者均设置;表单默认值 | 缺少标记、两者均设置时未发出警告、或标记只是复述表单默认值,均视为失败。 | audit:Field/behavior |
| FR8 | Field.test.tsx 中的 attached 层与局部堆叠(local-stacking)用例 |
attached、无状态、自定义控件 | 移除隔离或将根节点排布在其父级之外,均视为失败。 | audit:Field/code-health |
| FR9 | Field.test.tsx 中针对自定义控件的 attached 层用例 |
带有 attached 状态的自定义控件 | 该测试固定了当前的 attached 默认值,因此当 FR9 缺口闭合时,它会随之改变。 | audit:Field/behavior |
| PR1 | 证据缺口:没有测试断言不存在 per-field 全局资源 | — | — | audit:Field/code-health |
spec:AST-094 FR42 |
ButtonHitArea.interaction.browser.spec.ts 中的清除带(clear-band)与可清除 Selector 的 chevron 用例 |
文本输入框的清除按钮位于其文本旁;可清除 Selector 的清除按钮位于其 chevron 旁 | 清除带越过与文本或字段下一部分之间间距的一半,或点击 chevron 即触发清除,均视为失败。 | audit:Field/behavior |
| 主题结构(Theming anatomy) | scripts/check-knowledge.mjs;themingTargets.test.ts |
Field 根节点、标签、描述、调用方控件、状态、共享输入可供性(affordances)、指示器、工具提示 | 无效的排布,或渲染出的 class 不在已记录的 targets 中,均视为失败。 | audit:Field/theming |
| 文档投射(Documentation projection) | docPropLiterals.test.ts;docPropReferences.test.ts |
状态位置(placements)、labelIcon 及其他已记录的 props |
已记录的 literal(字面量)或 prop 引用偏离源类型,即视为失败。 | audit:Field/docs |
| RTL 适用性 | apps/storybook/rtl-audit/verified-not-applicable.json 中针对 core/Field 的条目 |
已检入的 Field stories | 某个 story 若获得方向性位置或行为,则会使 not-applicable 条目失效。 | audit:Field/i18n-rtl |
当前状态影响¶
- Attached 默认值(FR9)。 Field 对所有子元素默认将
statusVariant设为attached,这与family:input-fields/FR8相悖;如何迁移该默认值即为 OQ1。
决策日志¶
无组件级决策。Field 应用 family:input-fields 与 spec:AST-027。
开放问题¶
- OQ1 — Field 应如何迁移已发布的
attached默认值,使任意自定义控件不会获得family:input-fields/FR8所述其可能无法安全支持的 placement(位置)?(human-api)
内容边界¶
本文件不重复消费者 prop 表/示例、当前审计结果、实施步骤或 family/system 规则,而是链接到这些内容的拥有者。
本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 as/astryx