字段 widget 的错误提示键:spec 声明 `error`,objectui 渲染 `errorMessage`(declared ≠ enforced)

[os-zhuang]

在 objectui#3161(objectstack#4115 台账批次 7)对读 @object-ui/fields 与 spec 的 FieldWidgetProps 时发现,未在该 PR 修复(属行为变更)。

事实

@objectstack/spec/ui 的 FieldWidgetPropsSchema 是字段 widget 插件的 props 契约,它声明:

spec 键	objectui FieldWidgetComponentProps
error?: string	无——本地叫 errorMessage?: string
required: boolean(带 .default())	无
readonly: boolean(带 .default())	readonly?: boolean
field: { name?, label?, type: FieldType }	field: FieldMetadata(更宽)

也就是说:一个照着 spec 声明的 props 契约写出来的第三方字段 widget,放进 objectui 后校验消息不会显示,因为 objectui 传的是 errorMessage,widget 读的是 error;而且没有任何东西会报错——[key: string]: any(objectui#3221)让 props.error 成为合法读取,恒为 undefined。

需要拍板的是方向,不是修法

三种都成立,选哪个取决于 spec 的 FieldWidgetPropsSchema 是不是真的想当第三方 widget 的契约:

1. objectui 改名跟随 spec(errorMessage → error):48 个 widget + 调用点,一次性对齐,spec 成为唯一契约;
2. spec 改名跟随实现(error → errorMessage):spec 侧改动小,但 error 这个名字在 spec 里已经发布;
3. spec 退掉这份 props 契约:如果它从来不是给第三方 widget 用的(没有任何运行时读它),那它是一份"声明了但没人执行"的 schema,按 ADR-0049 enforce-or-remove 处理。

同类问题还有 required——spec 声明、objectui 的 widget 一律不接收(必填标记由外层 FieldContainer 画)。

关联:objectstack#4115、objectui#3161、objectui#3221。

[os-zhuang]

补一处同源现场:.github/prompts/component.prompt.md(给编码 agent 读的 prompt)把两层混成了一层,而且已经同时错了两处:

• 第 19/38 行说 @object-ui/fields 的 widget "Must implement FieldWidgetProps",但 Ref 指向 src/ui/widget.zod.ts——即 spec 的 schema;
• 第 174 行的示例写 import { FieldWidgetProps } from '@objectstack/spec/ui',然后当泛型用(FieldWidgetProps< number >)并解构一个 mode prop。spec 那个是 z.infer 出来的非泛型类型别名,也没有 mode 键;@object-ui/fields 那个才是泛型,也没有 mode。

也就是说照这份 prompt 写出来的字段 widget,导入的是一个不能带类型参数的类型、解构的是一个两边都不存在的 prop、并且(按本 issue)读不到校验消息。objectui#3161 只改了 @object-ui/fields 侧的符号名(FieldWidgetProps → FieldWidgetComponentProps),没有动这份 prompt:它的问题不是名字,是把"声明的契约"与"实现的 props"当成了同一个东西,而那正是本 issue 要拍板的方向。方向定了之后,这份 prompt 与 content/docs/guide/plugin-development.md、skills/objectui/guides/plugin-development.md 应当一起按结论重写。

---

Generated by Claude Code

[os-zhuang]

PM 裁决建议:走方向 1(objectui 跟随 spec),并且它不占用 v17 的 spec 窗口

先排除方向 3

方向 3 的前提是「如果它从来不是给第三方 widget 用的」。这个前提不成立——它是已发布的协议文档:

content/docs/protocol/objectui/widget-contract.mdx:48 写着「the source of truth is FieldWidgetPropsSchema」,:83-85 直接给出示例:

import type { FieldWidgetProps } from '@objectstack/spec/ui';

function CustomRatingField({ value, onChange, readonly, required, error }: FieldWidgetProps) {

**照这份文档写出来的 widget,required 和 error 恒为 undefined。**这不是一份「声明了但没人执行」的 schema,是一份「声明了、发布了、教了、然后不生效」的 schema——比 ADR-0049 点名的形态更坏一档。退掉它等于删掉一个协议页,而 objectui 的产品命题(第三方 / AI 编写的 widget)恰恰需要这份契约存在。

为什么是方向 1 而不是方向 2

按四轴:

• 防 AI 作者犯错:这是决定性的一轴。AI 作者读的就是 spec + 那份文档。今天「照着权威文档写」的产出物是一个静默坏掉的 widget,且 [key: string]: any(FieldWidgetComponentProps 的 [key: string]: any 让每个 widget prop 检查失效 #3221)让它连编译期都不报。方向 1 让「文档说的」和「能用的」第一次是同一个东西。
• 平台长远合理性:spec 是唯一契约,实现跟随契约。反过来(方向 2)是让已发布的协议名去追一个内部实现名。
• 实际业务需求:48 个 widget 的改名是机械的、可 grep 的、有编译器兜底的;required 本来就存在(只是由外层 FieldContainer 画),接进 props 不新增概念。
• 不扩边界:方向 1 不新增任何 spec 概念,零新增字段。

排期上的收获:这一项可以移出 v17 关键路径

这是我建议方向 1 的第二个理由,值得单独说:

方向	改 spec 吗	受 v17 窗口约束吗
1. objectui 跟随	否	否——只是 objectui 的 major
2. spec 跟随实现	是(改已发布的键名)	是
3. spec 退掉契约	是(移除导出)	是

也就是说:选方向 1,这件事就不再和 v17 的 spec 切版抢时间;选 2 或 3,它必须挤进 v17。在窗口本来就紧(9 个破坏性移除排队)的情况下,这是一个「正确的选择恰好也是最便宜的选择」的少数情形。

施工顺序有硬依赖

#3221 必须先落。索引签名还在的时候,props.error 是合法读取、类型 any——把 errorMessage 改名成 error 之后,任何漏改的调用点照样编译通过,改名的正确性无法被验证。先删索引签名(#3221),让编译器能看见这些键,再做 #3222 的对齐。

顺序:#3221 → #3222。两者都在 objectui 侧,不阻塞 v17。

---

Generated by Claude Code

[os-zhuang]

objectui#3221(PR #3230)已把 FieldWidgetComponentProps 的 [key: string]: any 换成封闭类型 —— 这条的前置条件满足了:props.error / props.required 现在是编译错误而不是静默 any,任何一种改名方案的正确性都可以由编译器验证。

按 #3221 的要求汇报一条边界结果,顺带一个我认为会改变本 issue 选型的证据。

1. 收紧类型后,error / errorMessage 的分歧没有在任何地方产生类型错误

全仓 turbo run type-check 78/78 绿。也就是说:今天没有任何代码读 props.error。分歧是潜伏的,不是在途的。

2. 但更尖锐的问题是:全仓没有任何宿主向 field widget 传 errorMessage

grep 全仓(排除 packages/fields/ 自身)后,没有一个调用点把 errorMessage 传给 field widget。表单渲染器用独立的 <FormMessage /> 渲染 react-hook-form 的校验信息,从不转发这个 prop;stripRegisteredFieldProps() 也没有任何构造它的路径。

而读它的有 7 个 widget:

• EmailField / CurrencyField / UrlField / RichTextField / PercentField / TextAreaField / PhoneField

它们的用法基本都是 aria-invalid={!!errorMessage} —— 一个恒为 undefined 的值。这意味着这 7 个 widget 的 aria-invalid 永远是 false,校验失败时屏幕阅读器拿不到该字段无效的信号。

这对本 issue 的选型意味着什么

这个槽位不只是名字和 spec 的 FieldWidgetPropsSchema 不一致 —— 它在两种拼写下都是死的。所以本 issue 的决策不是「改个名」,而是先回答「谁来生产它」:

• A. 只改名(errorMessage → error):与 spec 对齐,7 个 widget 改一行。但如果不接上生产者,结果是把一个死键改成另一个死键 —— declared ≠ delivered 的缺口原样保留,只是换了拼写。
• B. 改名 + 接上生产者:表单渲染器在渲染已注册 widget 时把 react-hook-form 的 fieldState.error?.message 一并传下去。aria-invalid 真正生效,契约两端都活。代价是要决定它与 <FormMessage /> 的关系(widget 只吃 aria-invalid、文案仍由 FormMessage 渲染,还是 widget 也渲染文案 —— 后者会双份显示)。
• C. 反向:删掉这个槽位,承认校验展示归表单渲染器所有,widget 不参与。那 spec 的 FieldWidgetPropsSchema.error 就该按 ADR-0049「enforce-or-remove」在 spec 侧处理,而不是在 objectui 侧补齐。

我的看法是 B:spec 已经声明了这个契约,而 aria-invalid 是真实的可访问性缺陷,不是纯命名问题;A 会让本 issue 关掉但缺陷留着,C 则要先在 @objectstack/spec 一侧立决定、跨仓。不过这是方向性判断,按 #3221 的范围边界我没有在 PR #3230 里动任何一行 —— 留给维护者定夺。

如果选 B,建议顺带补一条测试钉住「校验失败时该 widget 的 aria-invalid 为 true」,否则这个键会以第三种方式再死一次。

---

Generated by Claude Code

[os-zhuang]

更正我上一条的建议:方向仍是 1,但我把工作量说错了 —— 这个槽位在两种拼写下都是死的

#3221(PR #3230)删掉索引签名后本该暴露 error/errorMessage 的分歧,结果全仓 typecheck 全绿。我去查了为什么,事实比"命名不一致"尖锐得多,且我已独立核实:

全仓 packages/ + apps/ 中 `errorMessage=` 的**生产者**:0 处
packages/fields/src 中 `errorMessage` 的**读取**:15 处

没有任何宿主向 field widget 传过 errorMessage。 表单渲染器用独立元素渲染校验信息,从不转发这个 prop。

后果不只是"名字和 spec 不一致":Email / Currency / Url / RichText / Percent / TextArea / Phone 七个 widget 拿它算 aria-invalid={!!errorMessage},而它恒为 undefined——aria-invalid 从来没有被设置过。屏幕阅读器永远不知道这个字段校验失败了。这是一个当下就存在的可访问性缺陷,和 spec 叫什么名字无关。

所以我上一条把方向 1 描述成"改名 ~48 个 widget",这是错的

改名是较小的那一半。真正的问题是谁来生产它:

• 光改名 = 把一个没人传的 prop 换个名字,aria-invalid 依然永远不设置,spec 一致性变成纸面上的;
• 「容器渲染消息文本、widget 不需要知道」也不成立——aria-invalid 必须落在 input 元素本身,而 input 只有 widget 会渲染。容器渲染文字、widget 承载 a11y 状态,两者都需要这个信息。

修正后的建议:仍是方向 1,但工作定义变了

1. 表单渲染器开始生产这个 prop(这是实质工作,也是修掉 a11y 缺陷的那一步);
2. 槽位采用 spec 的名字 error,errorMessage 退役;
3. required 同理评估——spec 声明它,objectui 的 widget 一律不接收(必填标记由外层 FieldContainer 画)。但和 error 不同,required 是否需要下沉到 widget 取决于有没有 a11y 或行为上的必要(aria-required),不要默认照抄。

这反而加强了排除方向 3 的理由

方向 3 是"按 ADR-0049 退掉这份没人执行的 schema"。现在看得更清楚:spec 这份契约是对的,是 objectui 从来没实现它。退掉正确的契约来迁就未实现的现状,方向反了——而且会连带把已发布的协议文档(content/docs/protocol/objectui/widget-contract.mdx)一起作废。

排期结论不变

仍然不占 v17 的 spec 窗口:全部改动在 objectui 侧,spec 一个字不动。上一条评论里那张 A/B/C 表继续有效。

依赖关系也不变:#3221 先落(PR #3230 在跑),它让这件事变成编译器可判定的。

---

Generated by Claude Code

[os-zhuang]

更正上一条:正文里两处 < FormMessage /> 被 GitHub 的正文消毒器吞掉了(< 紧跟字母会被当成 HTML 标签在存储时剥离),读起来变成「表单渲染器用独立的 渲染校验信息」。补上被吃掉的组件名,其余不变:

• 表单渲染器用独立的 < FormMessage />(packages/components/src/renderers/form/form.tsx)渲染 react-hook-form 的校验信息,从不把 errorMessage 转发给 field widget。
• 选项 B「改名 + 接上生产者」的代价那一条,原文是:要决定它与 < FormMessage /> 的关系 —— widget 只吃 aria-invalid、文案仍由 < FormMessage /> 渲染,还是 widget 也渲染文案(后者会双份显示)。

结论不变:这个槽位在 error 和 errorMessage 两种拼写下都没有生产者,所以本 issue 的决策点是「谁来生产」,不只是「叫什么名字」。

---

Generated by Claude Code

[xuyushun441-sys]

认领:PM 循环第 7 轮 · v17 发布窗口:协议类优先
会话:session_01NVPjPzmmAJ2Ngtvgg5MSRa(objectui 分片 PM,账号 xuyushun441-sys)
分支:claude/issue-3222-field-widget-error-contract
Worktree:objectui-issue-3222

裁定:方向 1(objectui 跟随 spec),且必须是「改名 + 接上生产者」两件一起 —— 维护者已同意

综合上面四条评论的证据与两条评估轴,已与维护者确认。

排除方向 3

前提「如果它从来不是给第三方 widget 用的」不成立:content/docs/protocol/objectui/widget-contract.mdx 是已发布的协议页,:48 写着「the source of truth is FieldWidgetPropsSchema」,:83-85 的示例直接解构 { value, onChange, readonly, required, error };.github/prompts/component.prompt.md 同样教 error。这不是「声明了没人执行」的 schema,而是契约是对的、objectui 从来没实现它。退掉正确的契约去迁就未实现的现状,方向反了,还会连带作废一个协议页 —— 而"第三方 / AI 编写 widget"正是这份契约存在的理由。

排除方向 2

让已发布的协议名去追一个内部实现名,而且追的还是一个没人实现的键的名字。同时它要改 spec,占用 v17 切版窗口。

方向 1 的排期优势(这是选型的一部分,不是附带好处)

方向	改 spec	占 v17 窗口
1	否	否
2 / 3	是	是

⚠️ 工作定义:光改名是不够的

上面第三、四条评论的实测把这单的性质改了,派发按修正后的定义:

全仓 packages/ + apps/ 中 errorMessage 的生产者:0 处
packages/fields/src 中 errorMessage 的读取:15 处(7 个 widget)
读 props.error 的代码:0 处

这个槽位在两种拼写下都是死的。 后果不是纸面不一致:Email / Currency / Url / RichText / Percent / TextArea / Phone 七个 widget 拿它算 aria-invalid={!!errorMessage},而它恒为 undefined —— aria-invalid 从未被设置过,校验失败时屏幕阅读器拿不到该字段无效的信号。这是当下就存在的可访问性缺陷。

所以:只改名 = 把一个死键换成另一个死键,declared ≠ delivered 原样保留,只是换了拼写。

派发范围(五件,前两件是实质)

1. 表单渲染器开始生产这个 prop —— 渲染已注册 widget 时把 react-hook-form 的 fieldState.error?.message 作为 error 传下去。这是修掉 a11y 缺陷、也是让契约两端第一次都活的那一步。
2. 槽位采用 spec 的名字:errorMessage → error,7 个 widget + FieldWidgetComponentProps。机械改动,且 FieldWidgetComponentProps 的 [key: string]: any 让每个 widget prop 检查失效 #3221 已删索引签名,漏改点现在是编译错误而不是静默 any —— 改名的正确性可由编译器验证。
3. 文案职责划清:widget 只消费 error 驱动 aria-invalid;校验文案仍由 <FormMessage/> 渲染(packages/components/src/renderers/form/form.tsx)。widget 不要再渲染一份文案,否则双份显示。
4. 测试钉住「校验失败时该 widget 的 aria-invalid 为 true」 —— 否则这个键会以第三种方式再死一次。这是硬要求。
5. required 单独评估,不要默认照抄。spec 声明它、objectui 的 widget 一律不接收(必填星号由外层 FieldContainer 画)。它是否下沉取决于 aria-required 有没有真实的可访问性必要 —— 有就接,没有就在报告里说明理由并保持现状,不要为了对齐而对齐。

文档同步(定案的一部分)

方向定了之后,这三处应按结论重写(可同 PR 或紧随的 docs-only PR,你判断;若拆分请立单):

• content/docs/protocol/objectui/widget-contract.mdx
• .github/prompts/component.prompt.md —— 它今天同时错了两处:把 spec 的非泛型类型别名当泛型用(FieldWidgetProps<number>),并解构一个两边都不存在的 mode prop
• content/docs/guide/plugin-development.md / skills/objectui/guides/plugin-development.md

边界

⛔ 不动 packages/spec —— 方向 1 的全部意义就是 spec 一个字不改。若你发现必须改 spec 才能完成,停下来回报 needs_decision,那意味着选型前提有误。

⚠️ scope fence:packages/fields + packages/components/src/renderers/form/(+ 上述文档)。packages/components/src/renderers/form/form.tsx 上一小时刚合并过 #3271,先 fetch 最新 main。同期 agent 占用 packages/app-shell/**(#3268 / #3275 / #3229)与 packages/types+packages/core(#3201)。

---

Generated by Claude Code