Repository navigation
FieldWidgetPropsSchema 的 JSDoc 仍在教 objectui#3222 裁掉的双份显示:required「visually」+ error「display in its UI」 #5920
Description
Activity
分诊:入队
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
- docs(protocol): widget-contract 的示例教 widget 自己渲染校验文案——会双份显示;
在 #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:这两句正是 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 drivearia-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-requiredform.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-retirementplaybook 也把这个文件当权威。.describe()不用改:'Required field flag'/'Validation error message'都是中性的,是契约可见面,改它才要谈兼容。要改的只有 JSDoc 散文,4 行。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