[fields] 七个 widget 在**可编辑态**也丢掉 host 下发的 id —— label 的 `for` 悬空、description 零消费者(formula / summary / auto_number / vector / grid / slider / signature 实测)

[yinlianghui]

在 #4788(只读替换显示丢整份 host plumbing)的实施中实测发现的相邻一条,与那个 PR 无关也不由它引入,按 Prime Directive #10 立单(不认领、不扩围)。

#4788 修的是只读态:host 在「readonly + 注册 field widget」时包一层带 id / aria-labelledby / aria-describedby / role="group" 的容器。本条是同一族里 readonly 门管不到的那一半 —— 有七个 widget 在可编辑态也一样丢掉 host 下发的 id,因为它们根本没有可编辑分支,或者有分支但不展开 DOM pass-through。

实测

origin/main 1ef236e18,与 #4788 同一套 probe(真 form renderer + 裸注册,字段带 description: 'Some help',一行一个字段),看 editable 列:

formula editable for=DANGLING hostIdEl=NONE consumers=0
summary editable for=DANGLING hostIdEl=NONE consumers=0
auto_number editable for=DANGLING hostIdEl=NONE consumers=0
vector editable for=DANGLING hostIdEl=NONE consumers=0
grid editable for=DANGLING hostIdEl=NONE consumers=0
slider editable for=DANGLING hostIdEl=NONE consumers=0
signature editable for=DANGLING hostIdEl=NONE consumers=0

对照:其余 27 个注册的非 group-labelled 类型在 editable 列全部是 for=RESOLVES-LABELABLE hostIdEl=input/textarea/button consumers=1。

即:可见 label 的 for 指向一个整个文档里没有任何元素带的 id,只读态之外也一样 —— 这七个字段在无障碍树里没有名字,渲染出来的帮助文本零消费者。

为什么 #4788 的修法覆盖不到

#4788 的 host 门是 readonly === true。而在真实的对象表单路径上,计算型字段并不走 readonly:

packages/plugin-form/src/ObjectForm.tsx:687 把 formula / summary / auto_number 映射成 formField.disabled = true,不是 readonly: true。所以 ObjectForm 渲染出来的公式字段拿不到 #4788 的容器,for 照旧悬空。

另外三个(grid / slider / signature)与 readonly 无关:它们的唯一渲染分支就不展开 host props。

涉及文件

• packages/fields/src/widgets/FormulaField.tsx、SummaryField.tsx、AutoNumberField.tsx、VectorField.tsx —— 无可编辑分支,整个 widget 即显示面,签名把 props 收进 ...props 后只读 props.className;
• packages/fields/src/widgets/GridField.tsx、SliderField.tsx、SignatureField.tsx —— 有交互面,但渲染的元素上不展开 DOM pass-through;
• packages/plugin-form/src/ObjectForm.tsx:687 —— 计算型字段映射到 disabled 而非 readonly,是 D 组在真实表单里绕开 [fields] 非 group-labelled widget 的只读替换显示丢掉 host 下发的整份 plumbing —— label 的 for 悬空、description 零消费者(email / url / phone 实测) #4788 门的原因。

需要一次方向裁决,不要直接推

至少三种形状,取舍不同,不要按 #4788 外推:

1. 把 D 组映射成 readonly: true(改 ObjectForm)—— 最小,直接落进 [fields] 非 group-labelled widget 的只读替换显示丢掉 host 下发的整份 plumbing —— label 的 for 悬空、description 零消费者(email / url / phone 实测) #4788 已有的容器机制;但 disabled 与 readonly 在本仓是有意区分的两件事(form.tsx 的注释写明了),这条改的是语义分类而不只是 a11y;
2. 给 host 一个 display-only 声明(ComponentMeta 加一维,类似 labelling)—— 契约优先,host 不再靠「registered + readonly」推断;代价是新增一个公开契约键,且漏声明会静默退回今天的坏形状;
3. widget 侧各自展开 pass-through —— grid / slider / signature 有真控件,这条对它们大概是对的(host id 落到可 label 元素上,for 自然解析);但对 D 组无效,它们渲染的 span 不是 labelable 元素,for 落上去依然惰性([fields] 复合/分组 field widget 丢弃或错投 host 下发的控件 id：address / geolocation 的表单 label for 悬空，checkboxes / radio / rating / file 的 for 落在不可 label 的 div 上 #3961 当初换掉 for 的原因)。

三者可能要分组合用:grid / slider / signature 走 3,D 组走 1 或 2。

参考

• [fields] 非 group-labelled widget 的只读替换显示丢掉 host 下发的整份 plumbing —— label 的 for 悬空、description 零消费者(email / url / phone 实测) #4788 / 2026-08-16 维护者裁定(评论 5307576062)—— 只读态的 host 容器机制
• [fields] 复合/分组 field widget 丢弃或错投 host 下发的控件 id：address / geolocation 的表单 label for 悬空，checkboxes / radio / rating / file 的 for 落在不可 label 的 div 上 #3961 / PR fix(fields,components): 复合/分组 field widget 的组标签改用 IDREF 关联(#3961) #3978、[fields] multiselect 的 host label 也落在不可 label 的包裹 div 上 —— 与 #3961 同一失效类,但不在其审计的六个 widget 内 #3975 / PR fix(fields): name the multiselect chip group by IDREF instead of an inert for (#3975) #3983、[fields] 只读 / 零选项的 group-labelled 选项 widget 提前 return,groupDomProps 没被展开 —— host label 的 IDREF 没有消费者,标签仍然什么都不命名(#3961 的残留,checkboxes 今天的 main 上就这样) #3990 / PR fix(fields): group-labelled widget 的只读/零选项分支也消费 host label 的 IDREF (#3990) #4002、[fields] 只读态的 group-labelled 字段:description 的 IDREF 同样没有消费者(#3990 修的是「名」,这条是「描述」) #4005 —— group-labelled 一族
• [components] 内建 select 的空选项/依赖门态分支把 host id 落在一个 div 上 —— label 的 for 指向不可 label 元素,仍是不关联的 #3991 —— 内建 select 空选项分支的同类失效(host id 落在 div 上)

[os-zhuang]

Triage: needs-user-decision, type Bug. The card itself says "needs a direction ruling, do not extrapolate from #4788", and triage agrees: the candidate fixes disagree on whether the answer is a semantic re-mapping (disabled → readonly, changing a deliberately-distinguished classification), a new public contract key (a display-only declaration on ComponentMeta), or per-widget pass-through — and adding a contract key is the manual floor.

⚠️ Decide together with #4871 — same design axis, two hosts. #4871 (metadata-admin's SchemaForm + bare WIDGETS record) needs a per-widget labelling/display declaration for exactly the same reason this card's option 2 does. One ruling on "how does a host learn what a widget will render" should settle both; ruling them separately risks two divergent declaration shapes for one question.

Decision facets:

• Platform long-term coherence: option 2 (declared meta) generalizes the ruled labelling shape from [fields] 复合/分组 field widget 丢弃或错投 host 下发的控件 id：address / geolocation 的表单 label for 悬空，checkboxes / radio / rating / file 的 for 落在不可 label 的 div 上 #3961 and is the only option that also covers [app-shell] metadata-admin 的 SchemaForm 无条件给每个 widget 发 Label htmlFor={id},但 17 个注册 widget 里只有 5 个消费 id —— 分组类控件面的 for 悬空且组无可访问名 #4871's conditional-group case; option 1 quietly erases the repo's deliberate disabled/readonly distinction; option 3 fixes only the three widgets with real labelable controls.
• Measured business pull: seven field types render with no accessible name and dead help text in every editable object form, measured against a 27-widget green control group.
• AI-agent error-resistance: a declared labelling/display key is closed-enumeration and testable; the status quo (host infers from readonly) is the inference-that-silently-misses shape that produced this card. Note option 2's own trap, named by the card: an omitted declaration silently degrades — worth pairing with a registry-level gate.
• Startup scope discipline: likely composite (3 for grid/slider/signature, 1-or-2 for the display-only four); the smallest honest fix is not uniform, which is itself why this needs a ruling.

---

Generated by Claude Code

[os-zhuang]

Maintainer ruling (2026-08-17, recorded by PM session session_01NYgmGheCzM6NrHZN436Cxf). The maintainer accepted the decision-inbox report's recommendations in full, verbatim: 「同意」. Ruled together with #4871 — one declaration shape settles both hosts:

The declaration: the already-ruled ComponentMeta.labelling vocabulary (#3961) extends to a three-value closed enum — 'control' | 'group' | 'display' — as the single repo-wide answer to "how does a host learn what a widget will render". ⛔ No host-local variants. The declaration slice expands a public contract key ⇒ claude-fable-5 for that slice.

This card's landing:

• grid / slider / signature → option 3: expand DOM pass-through onto their real labelable controls (host id lands, for resolves naturally).
• formula / summary / auto_number / vector (display-only four) → declare 'display' and take the [fields] 非 group-labelled widget 的只读替换显示丢掉 host 下发的整份 plumbing —— label 的 for 悬空、description 零消费者(email / url / phone 实测) #4788-ruled host wrapper (id + aria-labelledby + aria-describedby + role="group").
• ⛔ Option 1 rejected — the disabled/readonly distinction is deliberate and stays; ObjectForm.tsx:687's mapping is not rewritten to buy a11y.
• Companion gate required: a registry-level check that every registered widget carries a declaration — an omitted declaration fails loudly instead of silently degrading (the trap the card itself named).

Label flipped needs-user-decision → pm:queue in the same stroke. Sibling ruling on #4871.

---

Generated by Claude Code

[yinlianghui]

【来自 #3318 残留批的实测 —— 不认领本单，只报两条:七分之二已在别处交付，以及本单「方案 3」对其中两个不成立】

实施 #3318 的账本残留时同一套 probe 重跑了本单的七行，读数与本单一致（for=DANGLING / hostIdEl=NONE / consumers=0 全中）。PR #4933（draft）作为 #3318 的交付，顺带关掉了这七行里的 slider 与 signature 两行:

 修前 修后
slider for=DANGLING hostIdEl=NONE consumers=0 name=IDREF hostIdEl=span[role=slider] consumers=1
signature for=DANGLING hostIdEl=NONE consumers=0 name=IDREF hostIdEl=div[role=group] consumers=1

剩余五行未动: formula / summary / auto_number / vector / grid。本单继续持有它们，D 组那条方向裁决（方案 1 vs 2）没有被本次交付预判掉。

⚠️ 一条要更正的地方: 本单「方案 3」对 slider / signature 单独用是不够的

本单正文写:

widget 侧各自展开 pass-through —— grid / slider / signature 有真控件，这条对它们大概是对的（host id 落到可 label 元素上，for 自然解析）

前半对、括号里那半不对，而这正是实施时踩到的一步。这两个 widget 确实有真控件，但控件本身不是 labelable 元素:

• slider 的控件是 Radix 的 span[role=slider] thumb;
• signature 的绘制面是 canvas。

label for 只能寻址 HTML 的 labelable 元素（button / input / meter / output / progress / select / textarea）。所以只做方案 3，for 会从「悬空」升级成「指向一个不可 label 的元素」—— getElementById 找得到、无障碍树里依然没有名字。probe 里 for=RESOLVES 会变绿而名字仍然缺失，是个会骗人的读数（本单的 RESOLVES-LABELABLE 那个写法是对的，值得保留成唯一口径）。

⇒ 这两个的正解是方案 3 + labelling: 'group' 声明（#3961 的 IDREF 路子），且是 file 的形态而非复合体的形态: 一个不可 label 的控件，不是一组子输入。PR #4933 即按此做——slider 的名字与描述直接落在 thumb 上（它的 slider 角色本身就能承载名字，不加多余的 group 包裹层）；signature 无可聚焦控件，落在 role="group" 容器上。

对 grid 的推断请重新量: 它在同一 probe 里 focusable=1 [button]，控件是个 button（labelable），所以方案 3 对它可能真的够——但这一条本次没有实测，别按上面两行外推。

与 #3318 的边界

#3318 只有 aria-invalid 一根轴，本单是 id / for / describedby 三根。两单在 slider / signature 上同因同治，所以 PR #4933 一次都关了；剩下五行的 aria-invalid 侧已在 #3318 的账本里按语义分流定案（四个只读展示型 + grid 各有归属），不代本单裁 id/describedby 侧的方向。

---

Generated by Claude Code