docs(spec): FieldWidgetPropsSchema 的 required/error JSDoc 不再教 objectui#3222 裁掉的双份显示 - #6062
Merged
Merged
Conversation
…i#3222 裁掉的双份显示 `required` 原文教 widget「indicate required state visually」、`error` 原文教 widget「display the error in its UI」——这两件事正是 objectui#3222 裁定反对、 并已在 objectui PR #3289 落地的:必填标记 `*` 归宿主 label,校验消息文案归宿主 `FormMessage`,widget 只把 `error` 当信号驱动 `aria-invalid`,再画一遍就是双份显示。 仅改 JSDoc 散文;`.describe()`、键名与类型一律不动(#5055 的 ADR-0049 决策面不受影响)。 Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011M7UwH25Unfi73UHim7ajY
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
qq9340100
added
the
skip-changeset
Claude
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_011M7UwH25Unfi73UHim7ajY
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 112 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
qq9340100
marked this pull request as ready for review
August 7, 2026 00:16
github-merge-queue
Bot
removed this pull request from the merge queue due to failed status checks
Aug 7, 2026
Contributor
⛔ merge queue 构建失败 — 先分诊，再决定要不要重排队列构建 31134114618 红了。队列跑的是全量套件（PR 侧 CI 只跑 affected 子集）， 失败的 job（日志抽取，best effort）：
历史信号：
分诊清单：
Generated by Claude Code · merge-queue-triage workflow (#4859) |
Contributor
|
队列管家:原样重投（命中 #5810 台账跨仓通用表第 1 行:基础设施抖动） 踢出事实（两读数判据，⛔ 未看 完整签名（取完整 job 归档判读，⛔ 未看 tail —— SKILL notes 7):
台账依据:跨仓通用表第 1 行「GitHub Actions runner 丢失 / npm registry 5xx / 网络超时(基础设施抖动，与 diff 无关)」⇒ 判定 已知环境抖动，处置 原样重投。本 PR 为 docs-only 的 spec JSDoc 改动，与 corepack 取包路径无任何交集。 已核让行(SKILL「双向让行」):处置前两次读本 PR 最近 30 分钟评论，仅有 00:29:54Z 的 已执行:重新挂 auto-merge(GraphQL)，PR 保持 open / 非 draft / ⛔ 本座位未合并、未切 ready/draft、未撤队、未重跑(rerun 复用原合并 ref，对本形态无效)、未动认领。 Generated by Claude Code |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #5920
问题
packages/spec/src/ui/widget.zod.ts里FieldWidgetPropsSchema的两段 JSDoc,教的正是 objectui#3222 裁定反对、且已在 objectui PR #3289 落地的两件事:required:"Widget should indicate required state visually and validate accordingly."*归宿主FormLabel(objectuiform.tsx:1484起);widget 再画一遍就是同一个星号两遍。objectui 的 widget props 里干脆没有required布尔键,spec-symbol-batch7.test.ts的_RequiredIsAbsent钉住error:"When present, widget should display the error in its UI."FormMessage(objectuiform.tsx:1614);widget 只把error当信号驱动aria-invalid(form.tsx:1563-1574)。再画一遍就是同一句文案两遍这与 #4866 / PR #5914 是同一处失实的两层:文档那层(
widget-contract.mdx)已修,而 #4866 的边界明确写死「不改widget.zod.ts」,所以 schema 这层留到了本单。危害面不是最终用户——实测这两句不进
content/docs/references/(生成文档只吃.describe())——而是读 schema 源码的人和 AI:AGENTS.md 要求 agent grep spec 判断契约,spec-property-retirementplaybook 也把这个文件当权威。改法
仅改 JSDoc 散文,4 行原文换成新的两段:
required:必填标记归宿主 label,widget 不自己画;校验同属宿主(它持有表单状态);widget 把状态反映到控件上的aria-required——AriaAttributes已声明该键,无需新增契约键(objectui#3290)。error:活动校验消息,字段有效时为undefined;当信号用驱动aria-invalid(控件是宿主够不到的那个元素),文案由宿主渲染,widget 再画一遍就是双份显示。⛔ 边界(严格按 issue 与认领评论):
.describe()('Required field flag'/'Validation error message')、键名、类型一律未动;同文件其它散文未动;#4866 / PR #5914 已修的 docs 面未动。与 #5055 的关系
#5055(同文件的 ADR-0049 enforce-or-remove,
pm:on-hold/target:v18)问的是「这套词表该不该存在」。本 PR 只动散文、不动契约面,无论 #5055 最终选退役还是选给载体,这两段都该是现在这个说法,因此不构成前置也不被它阻塞。验证
pnpm --filter @objectstack/spec build+check:generated:10/10 全绿,零生成物漂移(含check:docs)—— 与预期一致,JSDoc 不进.describe()生成流,工作树在 gate 跑完后仍然干净。pnpm --filter @objectstack/spec typecheck:通过(tsc --noEmit+check:test-typecheckOK)。pnpm --filter @objectstack/spec test:全绿。node scripts/check-nul-bytes.mjs:OK;另对改动文件做了控制字符自扫,无命中。Changeset
comment-only(纯 JSDoc 散文),不发布任何用户可见变更 ⇒ 无 changeset,建议
skip-changeset。🤖 Generated with Claude Code
https://claude.ai/code/session_011M7UwH25Unfi73UHim7ajY
Generated by Claude Code