fix(fields)!: FieldWidgetComponentProps 不再声称拥有全部键 (#3221)

[os-zhuang]

Fixes#3221

packages/fields/src/widgets/types.ts 里的 [key: string]: any 是 objectstack#4075 的机制:一个声称拥有全部键的类型,永远不可能被报告「缺了某个键」。本 PR 把它换成一个从真实调用点推导出来的封闭类型。

三个后果,逐条关掉

现象	之前	现在
props.required / props.error(spec 的 FieldWidgetPropsSchema 声明、本地没有)	合法读取,类型 any,运行时恒 undefined	编译错误
拼错 prop(readOnly vs readonly、onchange)	编译通过、静默失效	编译错误
对该类型做结构/parity 比较	原理上无效,批次 7 的符号守卫是唯一探测器	可比较了

新类型怎么定的:先读调用点,再写类型

Issue 给了两个候选。& React.HTMLAttributes< HTMLElement > 被排除,原因是实测的:它声明的 onChange?: FormEventHandler 与本契约的 onChange: (val: T) => void 在交集下冲突(strictFunctionTypes 逆变,赋值不成立),且不覆盖 data-*,更不覆盖 schema / dataSource / dependentValues 这些真正在传的键。

于是走「显式声明」。候选集不是猜的:先只删索引签名、跑 tsc,让编译器把真实缺口列出来,再逐条判断该不该存在。分三组:

• 受控输入契约(原有):value / onChange / field / readonly / disabled / className / errorMessage / onUploadingChange
• 宿主管道(表单渲染器 renderFieldComponent 与内联编辑宿主确实转发的):schema、dataSource、dependentValues、dependsOn、emptyHint、compact、onSelectRecord、onCreateNew
• DOM 透传:id、name、autoFocus、tabIndex、onBlur/onFocus/onClick、全部 aria-*(React.AriaAttributes,闭集),以及 data-*

data-* 用模板字面量索引签名而不是 [key: string]。这是关键区别:模板键让 keyof 保持有限,所以 props['data-testid'] 合法、props.required 依然报错 —— 开放的只是 HTML 本来就开放的那一族。

爆炸半径实测很小:全仓 turbo run type-check 78/78 绿,plugin-detail 内联编辑器、plugin-grid 单元格编辑器、app-shell 的 metadata inspectors、表单渲染器全部零改动通过 —— 因为封闭集就是从它们身上推出来的。

顺带:让读取侧也说实话

约 20 处 (props as any).x 改为直接读类型(compact、dataSource、disabled、name、id、onCreateNew、onSelectRecord、contextRecord、dependentValues)。留着它们等于保留了「拼错也能编译」那一半缺陷,而且恰恰留在最要命的位置上。

未动的是 (field || (props as any).schema) 这类元数据配置读取(约 25 处)—— 它们后面紧跟 as any,收紧收益低、风险高,且属于 field/schema 双载体问题,不在本 issue 范围内。

批次 7 的三条钉扎

_IndexSignatureStillThere / _RequiredSilentlyReadsAsAny / _ErrorSilentlyReadsAsAny 就是为本次改动写的、会在删除索引签名时报红的钉扎(#3224 已合并)。它们按预期删除了 —— 但没有留空,而是换成反向断言(类型现在是封闭的、两个键确实缺失),再加一条 data-* 仍开放的钉扎。这样把类型重新放宽回 [key: string] 会失败一个测试,而不是悄悄通过。

新增 packages/fields/src/__tests__/widget-props-contract.test.tsx:用 @ts-expect-error 钉住四类拒绝(required、error、readOnly、onchange),用一个正向字面量钉住每个透传键仍被接受(过度收紧会报红),再用两个渲染断言证明 aria-* / data-* / disabled 真的还能到达控件 —— 封闭类型不能是靠丢掉真实行为换来的。

范围边界:没有碰 #3222

没有把 errorMessage 改名为 error,没有新增 required。本 PR 只让类型说实话,好让 #3222 变成编译器可判定的问题。

按要求汇报:移除索引签名后,error/errorMessage 的分歧没有在任何地方产生类型错误(全仓 typecheck 全绿)。查证下来原因比「命名分歧」更尖锐,这条直接关系到 #3222 的选型,已同步评论到该 issue:

全仓没有任何宿主向 field widget 传 errorMessage。 表单渲染器用独立的 < FormMessage /> 渲染校验信息,从不转发这个 prop。读它的 7 个 widget(Email/Currency/Url/RichText/Percent/TextArea/Phone)拿它算 aria-invalid={!!errorMessage},而它恒为 undefined —— 所以这 7 个 widget 的 aria-invalid 永远是 false。

也就是说这个槽位不只是名字和 spec 不一致,它在两种拼写下都是死的。#3222 的决策因此不只是改名,而是「谁来生产它」。

注:上一版正文里 < FormMessage /> 被 GitHub 的正文消毒器当成 HTML 标签吞掉了(< 紧跟字母)。此处及后续一律在 < 后留一个空格。

验证

pnpm --filter @object-ui/fields type-check → exit 0
npx turbo run type-check --concurrency=2 → 78 successful, 78 total
npx turbo run build --filter=!@object-ui/site → 43 successful, 43 total
npx vitest run packages/fields/ (根配置) → 38 files / 483 tests passed
pnpm --filter @object-ui/fields lint → 0 errors
node scripts/check-spec-symbol-derivation.mjs → exit 0(未修改该脚本)
node scripts/check-changeset-fixed.mjs → exit 0

顺带发现(已另开 issue,不在本 PR 修)

• 表单渲染器计算的 emptyHint 被每个选项 widget 丢弃,用户看到的是硬编码英文 #3231 —— 表单渲染器计算的 emptyHint 被四个选项 widget 全部丢弃,用户看到的是硬编码英文(绕过 i18n)。
• TextAreaField 读取的 mobileFullscreen prop 全仓无人生产,注释却说"宿主表单传入" #3232 —— TextAreaField 读取的 mobileFullscreen 全仓无人生产,注释却声称「宿主表单传入」。

两条都是同一类:索引签名在时,「读了但没人写」根本不可能被看见。

🤖 Generated with Claude Code

https://claude.ai/code/session_01PRJtkgUAaVG11FsJQbvZWA

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 2, 2026 8:25pm

[github-actions]

✅ Console Performance Budget

Metric	Value	Budget
Main entry (gzip)	28.1 KB	350 KB
Entry file	index-C51mv2gK.js	—
Status	PASS	—

---

📦 Bundle Size Report

Package	Size	Gzipped
app-shell (index.js)	8.47KB	3.09KB
app-shell (runtime-config.js)	7.42KB	2.32KB
app-shell (types.js)	0.01KB	0.04KB
app-shell (urlParams.js)	7.57KB	2.97KB
auth (AuthContext.js)	0.31KB	0.24KB
auth (AuthGuard.js)	1.17KB	0.53KB
auth (AuthProvider.js)	22.10KB	4.37KB
auth (AuthShell.js)	3.49KB	1.40KB
auth (ForgotPasswordForm.js)	12.12KB	3.41KB
auth (LoginForm.js)	17.86KB	5.29KB
auth (PreviewBanner.js)	0.90KB	0.50KB
auth (RegisterForm.js)	6.43KB	2.09KB
auth (SocialSignInButtons.js)	9.60KB	3.89KB
auth (UserMenu.js)	3.40KB	1.22KB
auth (auth-gate-events.js)	1.29KB	0.66KB
auth (authStyles.js)	5.04KB	1.72KB
auth (createAuthClient.js)	35.76KB	9.11KB
auth (createAuthenticatedFetch.js)	4.37KB	1.69KB
auth (index.js)	2.35KB	1.07KB
auth (org-roles.js)	6.66KB	2.78KB
auth (phone-identifier.js)	1.11KB	0.66KB
auth (types.js)	0.59KB	0.35KB
auth (useAuth.js)	4.91KB	0.87KB
auth (useIsWorkspaceAdmin.js)	1.61KB	0.85KB
collaboration (CommentThread.js)	18.38KB	4.49KB
collaboration (LiveCursors.js)	3.17KB	1.27KB
collaboration (PresenceAvatars.js)	3.65KB	1.42KB
collaboration (PresenceProvider.js)	2.79KB	1.13KB
collaboration (index.js)	1.25KB	0.53KB
collaboration (useCommentSearch.js)	1.98KB	0.88KB
collaboration (useConflictResolution.js)	7.75KB	1.86KB
collaboration (useMentionNotifications.js)	1.81KB	0.68KB
collaboration (usePresence.js)	6.33KB	1.84KB
collaboration (useRealtimeSubscription.js)	7.91KB	2.01KB
components (index.js)	476.12KB	104.47KB
core (index.js)	2.25KB	0.80KB
create-plugin (index.js)	9.28KB	2.98KB
data-objectstack (index.js)	136.23KB	34.75KB
fields (index.js)	223.43KB	54.66KB
i18n (LocalizationContext.js)	1.76KB	0.96KB
i18n (currency.js)	1.22KB	0.64KB
i18n (i18n.js)	4.32KB	1.77KB
i18n (index.js)	2.46KB	0.96KB
i18n (pickLocalized.js)	1.70KB	0.83KB
i18n (provider.js)	5.37KB	1.72KB
i18n (useObjectLabel.js)	26.14KB	6.07KB
i18n (useSafeTranslation.js)	3.26KB	1.44KB
layout (index.js)	37.91KB	10.53KB
mobile (MobileProvider.js)	0.92KB	0.49KB
mobile (ResponsiveContainer.js)	0.94KB	0.38KB
mobile (breakpoints.js)	1.51KB	0.70KB
mobile (createOfflineDataSource.js)	5.61KB	1.74KB
mobile (index.js)	1.50KB	0.62KB
mobile (offlineQueue.js)	3.91KB	1.35KB
mobile (pwa.js)	0.97KB	0.49KB
mobile (serviceWorker.js)	1.48KB	0.62KB
mobile (serviceWorkerSource.js)	3.41KB	1.48KB
mobile (useBreakpoint.js)	1.54KB	0.65KB
mobile (useGesture.js)	6.96KB	1.98KB
mobile (useOfflineSync.js)	1.99KB	0.72KB
mobile (usePullToRefresh.js)	2.53KB	0.85KB
mobile (useResponsive.js)	0.71KB	0.42KB
mobile (useResponsiveConfig.js)	1.36KB	0.63KB
mobile (useSpecGesture.js)	4.05KB	1.53KB
mobile (useTouchTarget.js)	1.01KB	0.54KB
permissions (MePermissionsProvider.js)	8.75KB	3.06KB
permissions (PermissionContext.js)	0.31KB	0.25KB
permissions (PermissionGuard.js)	0.89KB	0.45KB
permissions (PermissionProvider.js)	3.67KB	1.12KB
permissions (evaluator.js)	4.41KB	1.44KB
permissions (index.js)	0.91KB	0.41KB
permissions (store.js)	0.91KB	0.42KB
permissions (useFieldPermissions.js)	1.28KB	0.52KB
permissions (usePermissions.js)	1.55KB	0.71KB
plugin-ai (index.js)	15.71KB	3.79KB
plugin-calendar (index.js)	44.90KB	12.35KB
plugin-charts (index.js)	60.53KB	17.12KB
plugin-chatbot (index.js)	180.09KB	42.72KB
plugin-dashboard (index.js)	111.87KB	28.82KB
plugin-designer (index.js)	210.51KB	42.50KB
plugin-detail (index.js)	230.54KB	56.77KB
plugin-editor (index.js)	2.46KB	1.10KB
plugin-form (index.js)	111.39KB	26.94KB
plugin-gantt (index.js)	162.26KB	39.53KB
plugin-grid (index.js)	185.04KB	49.00KB
plugin-kanban (index.js)	47.82KB	13.18KB
plugin-list (index.js)	104.86KB	25.30KB
plugin-map (index.js)	16.80KB	5.24KB
plugin-markdown (index.js)	13.65KB	4.67KB
plugin-report (index.js)	40.48KB	10.57KB
plugin-timeline (index.js)	25.76KB	7.32KB
plugin-tree (index.js)	8.34KB	2.82KB
plugin-view (index.js)	83.54KB	20.39KB
providers (DataSourceProvider.js)	0.75KB	0.39KB
providers (MetadataProvider.js)	1.37KB	0.59KB
providers (ThemeProvider.js)	1.90KB	0.85KB
providers (UploadProvider.js)	11.71KB	3.53KB
providers (index.js)	0.44KB	0.22KB
providers (types.js)	0.01KB	0.04KB
react-runtime (index.js)	5.67KB	2.37KB
react (LazyPluginLoader.js)	3.77KB	1.33KB
react (SchemaRenderer.js)	19.28KB	6.38KB
react (data-invalidation.js)	5.05KB	2.08KB
react (index.js)	1.02KB	0.55KB
react (spec-input.js)	0.20KB	0.18KB
sdui-parser (codegen.js)	4.09KB	1.74KB
sdui-parser (index.js)	4.47KB	2.03KB
sdui-parser (parse.js)	10.04KB	2.82KB
sdui-parser (types.js)	0.29KB	0.24KB
sdui-parser (validate.js)	4.69KB	1.48KB
types (ai.js)	0.20KB	0.17KB
types (api-types.js)	0.20KB	0.18KB
types (app.js)	2.87KB	0.99KB
types (base.js)	0.20KB	0.18KB
types (blocks.js)	0.20KB	0.18KB
types (complex.js)	0.20KB	0.18KB
types (crud.js)	0.20KB	0.18KB
types (data-display.js)	0.20KB	0.18KB
types (data-protocol.js)	0.20KB	0.19KB
types (data.js)	0.20KB	0.18KB
types (designer.js)	1.87KB	0.85KB
types (disclosure.js)	0.20KB	0.18KB
types (error-code.js)	1.54KB	0.88KB
types (feedback.js)	0.20KB	0.18KB
types (field-types.js)	0.20KB	0.18KB
types (form.js)	0.20KB	0.18KB
types (http-retry.js)	4.32KB	2.02KB
types (index.js)	2.46KB	1.21KB
types (layout.js)	0.20KB	0.18KB
types (managed-by.js)	0.19KB	0.18KB
types (mobile.js)	0.20KB	0.18KB
types (navigation.js)	0.20KB	0.18KB
types (objectql.js)	0.20KB	0.18KB
types (overlay.js)	0.20KB	0.18KB
types (permissions.js)	0.20KB	0.18KB
types (plugin-scope.js)	0.20KB	0.18KB
types (record-components.js)	0.20KB	0.19KB
types (record-semantics.js)	1.28KB	0.67KB
types (registry.js)	0.20KB	0.18KB
types (reports.js)	0.20KB	0.18KB
types (spec-report.js)	5.05KB	1.93KB
types (system-fields.js)	3.33KB	1.54KB
types (theme.js)	0.20KB	0.18KB
types (ui-action.js)	3.40KB	1.71KB
types (views.js)	0.20KB	0.18KB
types (widget.js)	0.20KB	0.18KB

Size Limits

• ✅ Core packages should be < 50KB gzipped
• ✅ Component packages should be < 100KB gzipped
• ⚠️ Plugin packages should be < 150KB gzipped

[os-zhuang]

PM 验收:ACCEPT,放行合并队列

CI 15 项 13 绿 2 skipped、零红,已独立复核。范围边界守住:errorMessage 未改名、required 未新增。

定类型的方法是对的:先让编译器列缺口,再逐条判断

没有猜该声明哪些键,而是先只删索引签名、跑 tsc,让它列出 52 个真实缺口,再逐条判断该不该存在。这是这类改动唯一可靠的做法——凭直觉列白名单,要么漏键(炸下游)、要么多列(把索引签名换成一堆没人用的可选键,防御力照样是零)。

爆炸半径的证据也给对了:全仓 78/78 绿,且 plugin-detail 内联编辑器、plugin-grid 单元格编辑器、app-shell inspectors、表单渲染器零改动通过——因为封闭集就是从它们身上推出来的。"没有下游需要改"在这里不是运气,是方法的必然结果。

排除 & React.HTMLAttributes<HTMLElement> 也是基于实测而非品味:它的 onChange?: FormEventHandler 在 strictFunctionTypes 下与本契约的 onChange: (val: T) => void 逆变冲突,且不覆盖 data-* 与真正在传的领域键。

data-* 用模板字面量索引签名是这个 PR 的关键手法

`data-${string}` 让 keyof 保持有限,所以 props['data-testid'] 合法、而 props.required 依然报错。开放的只是 HTML 本来就开放的那一族。这正好躲开了 objectstack#4075 的机制——问题从来不是"有索引签名",而是"keyof 变成了 string"。这条值得记进方法学。

把三条钉扎换成反向断言,而不是删空

批次 7 那三条(_IndexSignatureStillThere / _RequiredSilentlyReadsAsAny / _ErrorSilentlyReadsAsAny)按预期删除,但换成了反向断言 + data-* 仍开放的钉扎。于是把类型重新放宽回 [key: string] 会失败一个测试,而不是悄悄通过。删掉一条守卫时用相反方向的守卫接上——这是正确做法,不是"顺手把测试删了"。

正向字面量钉住每个透传键仍被接受(过度收紧会报红)、两条渲染断言证明 aria-* / data-* / disabled 真的还能到达控件,这两条同样必要:封闭类型不能是靠丢掉真实行为换来的。

约 20 处 (props as any).x 一并改掉,是对的

留着它们等于保留了"拼错也能编译"那一半缺陷,而且恰恰留在最要命的位置。未动的约 25 处 field || (props as any).schema 属于下面那个双载体问题,不在本单范围——这个切分正确。

open question(field / schema 双载体)我不在本 PR 处置,另开单

recommendation 是"B 最终、A 现在",而 A 正是本 PR 所发。同意:不阻塞。但我不会照 B 直接派工,理由见新单——schema 是 SchemaRenderer实际传给 widget 的键,第三方 widget 可能在读它,这和 #3226 是同一个陷阱(仓内证据回答不了仓外消费者的问题)。已另开单记录,按用户指示本轮后暂停,不派发。

#3231 / #3232 两条越界发现已入队。

---

Generated by Claude Code