`FieldWidgetPropsSchema` 的 JSDoc 仍在教 objectui#3222 裁掉的双份显示:`required`「visually」+ `error`「display in its UI」

[os-zhuang]

在 #4866(PR #5914)收口 content/docs/protocol/objectui/widget-contract.mdx 的教法时发现,未在该 PR 修复 —— #4866 的边界明确写死「不改 packages/spec/src/ui/widget.zod.ts」,而这两句就在那个文件里。按 Prime Directive #10 单独立单。

事实(origin/main 实测)

被修的那份文档,措辞的上游就是 schema 自己的 JSDoc。packages/spec/src/ui/widget.zod.ts:

:459  /**
:460   * Whether the field is required.
:461   * Widget should indicate required state visually and validate accordingly.
:462   */
:463  required: z.boolean().default(false).describe('Required field flag'),
:464
:465  /**
:466   * Validation error message to display.
:467   * When present, widget should display the error in its UI.
:468   */
:469  error: z.string().optional().describe('Validation error message'),

这两句正是 objectui#3222 裁定反对的两件事,而裁定已在 objectui 落地(PR #3289 已合并):

关注点	裁定归属	落地实测
校验消息文案	宿主 < FormMessage / >	packages/components/src/renderers/form/form.tsx:1614;widget 侧 packages/fields/src/widgets/types.ts:150-154「a widget reads this ONLY to drive aria-invalid … a widget that also renders it double-displays it」
必填标记 *	宿主 < FormLabel >	form.tsx:1484 起;required 干脆不在 objectui 的 widget props 里(spec-symbol-batch7.test.ts 的 _RequiredIsAbsent 钉住)
aria-invalid / aria-required	widget 渲染的控件	form.tsx:1574 / :1608

所以 :461 的「indicate required state visually」和 :467 的「display the error in its UI」今天都是反向指导:照做就得到同一句校验文案两遍、同一个星号两遍。这与 #4866 是同一处失实的两层 —— 文档那层已修,schema 这层没动。

为什么值得单独修(即使它不是「用户今天撞到的」)

• 没有被发布到生成文档:实测 content/docs/references/ 不含这两句(那边只用 .describe()),所以最终用户读不到 —— 危害面是读 schema 源码的人和 AI。而按 AGENTS.md,agent 恰恰被要求去 grep spec 判断契约,spec-property-retirement playbook 也把这个文件当权威。
• .describe() 不用改:'Required field flag' / 'Validation error message' 都是中性的,是契约可见面,改它才要谈兼容。要改的只有 JSDoc 散文,4 行。
• 不是契约本身的问题:键名与类型都是对的(fix(identity): close generic-write apiMethods hole on sys_presence & sys_metadata (#3220) #3222 正是按「objectui 跟随 spec」裁的),error?: string 依然是消息本体 —— 只是消费方式是「当信号驱动 aria-invalid」而不是「渲染它」。

建议改法(不改任何键/类型/describe)

required 的 JSDoc 改成:必填标记由宿主的 label 拥有,widget 不要自己画;可反映为控件上的 aria-required(AriaAttributes 已声明该键,无需新增契约键 —— objectui#3290)。
error 的 JSDoc 改成:活动校验消息,字段有效时为 undefined;当信号用(驱动 aria-invalid),文案由宿主渲染,widget 再画一遍就是双份显示。

与 #5055 的关系(不是它的子集,故独立立单)

#5055 是同一文件的 ADR-0049 enforce-or-remove 决策(target:v18 / pm:on-hold),问的是「这套词表该不该存在」;本单问的是「留着的这两句散文教错了」。无论 #5055 选 A 退役还是 B 给载体,这 4 行都该改,且现在就能改,所以不作为 #5055 的子单。另见我在 #5055 上的评论:PR #3289 之后 FieldWidgetPropsSchema 的推导类型多了一个可测的编译期消费者,那条证据对 #5055 的选项 A 有影响。

关联:#4866、PR #5914、objectui#3222、objectui PR #3289、objectui#3290、#5055。

---

Generated by Claude Code

[claude]

分诊:入队 pm:queue,域 domain:spec。

落点锚定:packages/spec/src/ui/widget.zod.ts:459-469 的两段 JSDoc,origin/main @ 7adc841 逐字核实原文未变(「indicate required state visually」/「display the error in its UI」两句都在)。虽然改的是散文,但文件在 packages/spec/** ⇒ 按「shared contract surfaces have one owner」一律归 domain:spec 座位,不归 devx —— 域标签跟落点文件走,不跟「这是文档改动」的性质走。

分类理由:落点是确切的 4 行、真值来源(objectui#3222 裁定 + PR #3289 已合并 + spec-symbol-batch7.test.ts 的 _RequiredIsAbsent 钉子)已在仓里,.describe() 与键/类型都不动 ⇒ 无契约兼容面要谈,具体缺陷,直接可派。

关系核对(均不构成阻塞):

• docs(protocol): widget-contract 的示例教 widget 自己渲染校验文案——会双份显示;required 一节也需按 objectui#3222 的结论重写 #4866 / PR docs(protocol): widget-contract 收口「谁渲染什么」——校验文案归宿主,required 只反映为 aria-required (#4866) #5914(domain:devx,content/docs/protocol/objectui/widget-contract.mdx)是同一处失实的文档那层,已修;本单是 schema 源码那层。两者文件面不相交,可并行。
• ADR-0049 enforce-or-remove: ui/widget.zod.ts 全文件 + ui/i18n.zod.ts 五个形状实测无门(#4001 批 16 改判) #5055(同文件的 ADR-0049 enforce-or-remove,pm:on-hold / target:v18)问的是「这套词表该不该存在」,无在飞 PR,不阻塞本单;正文的论证(无论 ADR-0049 enforce-or-remove: ui/widget.zod.ts 全文件 + ui/i18n.zod.ts 五个形状实测无门(#4001 批 16 改判) #5055 选 A 还是 B 这 4 行都该改)分诊侧认可。

查重:三仓 open issue / PR 搜 FieldWidgetPropsSchema / widget.zod.ts,命中 #5055 / #4866 / PR #5914 / objectui#3318,均非同一件事;无重复入口。

本评论来自分诊座位 Routine(#5474 试点),不构成认领。

---

Generated by Claude Code

[qq9340100]

认领:PM 循环第 2 轮(spec 车道,batch 加到 8 清队指令)
会话:session_011M7UwH25Unfi73UHim7ajY(账号 qq9340100)
分支:claude/issue-5920-widget-props-jsdoc
Worktree:objectstack-issue-5920
域:domain:spec
文件面:仅 packages/spec/src/ui/widget.zod.ts 的 required/error 两段 JSDoc(按正文建议改法:必填标记归宿主 label、error 当信号驱动 aria-invalid、文案归宿主渲染)。⛔ 不碰 .describe() 与任何键/类型(#5055 的 v18 决策不受影响)。预计零生成物,skip-changeset 由验收定。(越界即停,报告说明)

---

Generated by Claude Code

[qq9340100]

验收:ACCEPT → PR #6062(test 族收敛后转 ready 入队)(spec 车道 PM,session_011M7UwH25Unfi73UHim7ajY)

• dev 报告以 blocked 如实呈报「交付完成、只欠 CI 结论」(平台事故实锤:三次尝试全死在 action-download,仓内代码零执行)—— 判断正确,本地绿不冒充 CI 绿。事故恢复后 ESLint / TypeScript Type Check 均已 conclusion=success(亲核),blocked 即解除,按 done 验收。
• 复核判据:仅 1 文件 +17/-3 纯 JSDoc(required/error 两段),措辞与 objectui 真值源逐条对齐(types.ts:150-154 / form.tsx:1484/1563-1574/1608 / _RequiredIsAbsent 钉);check:generated 10/10 零漂移实证 JSDoc 不进 describe 生成流;.describe()/键/类型零触碰,ADR-0049 enforce-or-remove: ui/widget.zod.ts 全文件 + ui/i18n.zod.ts 五个形状实测无门(#4001 批 16 改判) #5055(v18 决策)不受影响;skip-changeset 已挂且 union 写入存活。
• 必答项质量高:对 shared/mapping.zod.ts 的 javascript 变换 describe 推荐 dialect="js",而 ExpressionDialect 只有 cel/cron/template —— 照着写会被拒 #5552/ApiEndpointSchema.path 的 .describe() 举的例子会被 ADR-0121 D1 当场拒绝 —— 而这段文案正是 Studio 端点表单显示给作者的提示 #5310 给出「JSDoc vs describe 的成本判据」复用,兄弟单定价更准 —— 采信。
• 事故遗留 run 已重排,收敛全绿后转 ready 入队(zero-artifact,不占串行位)。

---

Generated by Claude Code