Uh oh!
There was an error while loading. Please reload this page.
feat(spec): element:record_picker 补声明扁平 sort / limit(#6276 · A 案) - #6624
Merged
Conversation
…rthands (#6276) The picker's renderer resolves its query from four keys through one identical `ds.<k> ?? props.<k>` pattern (objectui `record-picker.tsx`): const object = ds.object ?? props.object; const filter = ds.filter ?? props.filter; const sort = ds.sort ?? props.sort; const limit = ds.limit ?? props.limit ?? 50; After #5775 the first two flat spellings were declared and the last two were not, so one renderer read half a contract and half a trapdoor: an author who inferred `properties.limit: 20` from the `object`/`filter` spelling got the renderer's default 50 with zero diagnostics, because the key was stripped before anything could read it. ADR-0078, on the element #5775 had just been written to fix. Maintainer ruling 2026-08-08, direction A — the #5611 rule applied again: the delivered, authorized shape is the contract. Both keys take the shape `ElementDataSourceSchema` already declares for its own `sort` / `limit` (`SortItemSchema[]`, positive integer), imported from the shared source rather than re-spelled, so the shorthand cannot drift into a third dialect. `dataSource.*` still wins when both are written — the declaration documents the precedence, it does not change it. The renderer's `?? 50` stays a renderer fallback and is deliberately NOT a schema default: `.default(50)` would materialize a limit on every parsed picker and turn an unset key into an authored one. Direction B (retire the flat family, make `dataSource` the single door) is not dropped — it is a cross-element decision tracked as #6590 for v18, and this change does not block it. - packages/spec/src/ui/component.zod.ts — the two declarations + the rule the next divergence sweep should follow (enumerate by the renderer's read pattern, not by the key list a previous ruling quoted) - packages/spec/src/ui/component.test.ts — retention, value rejection, and shape parity with `ElementDataSourceSchema` - packages/lint/src/validate-component-props.test.ts — the #5068 gate half: the keys stop being unknown-key findings, and a wrong `limit` is now judged instead of stripped - generated: authorable-surface/ui.json, content/docs/references/ui/component.mdx Refs #6276, #5775, #5068, #6590, ADR-0078
…ord-picker-sort-limit
…/main main's inline-shape depth budget changed how nested shapes render in the generated reference, so my pre-merge `gen:docs` output and main's generator merged clean but were jointly wrong (`PageTabsProps.items[].visibleWhen` expanded on my side, collapsed on main's). Regenerated against the merged generator — the delta vs main is now exactly the two `element:record_picker` rows this PR adds.
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
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 8, 2026 07:48
Uh oh!
There was an error while loading. Please reload this page.
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 freeto join this conversation on GitHub.
Already have an account?
Sign in to comment
2 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#6276
裁决依据
维护者 2026-08-08 在 issue 上裁定 A 案（裁决评论）：补声明
sort/limit，element:record_picker的四个扁平简写全部成为契约。理据是 #5775 的同一条判例 —— 以被兑现的形状为准。同时裁决明确：B 案不废弃，升格为方向性议题另立 #6590 挂 v18 评估（
dataSource唯一入口 + 扁平简写族整体退役）。A 不堵 B —— 届时sort/limit与object/filter一起走 ADR-0087，这两个键是一起退役的，不是新增的债。前提复核（已核实，成立）
objectui HEAD
7894432的packages/components/src/renderers/basic/record-picker.tsx仍是四键同一模式，dataSource优先、扁平简写兜底：本仓
origin/main上（#5775 落地后）object/filter已声明，sort/limit未声明 —— 同一个 renderer 的同一组兜底，一半是契约、一半是暗门。一个照着object/filter写法推断出properties.limit: 20的作者，拿到的是 renderer 默认的 50 条，零诊断：键在任何东西读到它之前就被 strip 掉了，#5068 闸门把它报成未声明键，值检查从未运行。这正是 ADR-0078 的形状，出现在 #5775 刚刚为此重写过的那个 element 上。改动
形状对齐
dataSource内的同名键，而且是从同一份源导入而非另抄一遍 —— 它们是同一份契约的第二种拼写，形状分叉就会变成第三种 sort 方言（strictness ledger 的report.zod.ts行已经记了三种）：describe()写明兜底次序：dataSource.sort/dataSource.limit在两者都写时优先 —— 声明只是把既有优先级写进契约，不改变它。renderer 的
?? 50刻意不做成 schema default。.default(50)会让每一次 parse 都物化出一个limit: 50，把「没写」变成「写了」，而且从此要靠人手和 objectui 保持同步。它是 renderer 的兜底，文档里写清楚，声明里不写。测试与验证
packages/spec/src/ui/component.test.ts（6 条）—— 保留（不被 strip）、值判决（非法limit/ 非法sort按名拒绝）、与ElementDataSourceSchema的形状一致性（同一个值两个门 parse 结果相同、同一个非法值两个门判决相同）、以及「不 default」这一条。packages/lint/src/validate-component-props.test.ts（2 条）—— #5068 闸门的另一半：两个键不再是 unknown-key 发现，且一个错的limit现在被判值而不是被静默 strip。逆向验证（方向先判后跑）。 预判：这是 additive 声明落在 strip 模式的
z.object()上，撤回后sort/limit会被静默 strip，所以保留类与拒绝类断言应当全红；唯一例外是「不 defaultlimit」那条 —— 撤回前后limit都是undefined，它是控制项，本就无法区分方向。实测与预判一致：一条计划外的读数，值得记下来： 撤回声明后
gen:schema自己就红了 —— authorable-surface 的删除闸门报2 authorable key(s) disappeared from the contract。也就是说这两个键从落地这一刻起就被闸门锚住了：将来 #6590 真要退役它们，只能走 tombstone + D2 conversion + major changeset，不可能被谁顺手删掉。生成物与闸门
pnpm --filter @objectstack/spec testpnpm --filter @objectstack/lint testtypecheck（spec + lint）check:scripts-typecheck/check:test-typecheck）check:generatedcheck:spec-parsed-aliaspnpm lint（ESLint）check:nul-bytes/doc-authoring/adr-anchors/empty-changeset/quick-reference-counts/role-word/docs-audit-scope生成物只动了两行：
packages/spec/authorable-surface/ui.json加两个键、content/docs/references/ui/component.mdx加两行表格。ADR-0122： 复用已有具名 schema
SortItemSchema，未产生新具名 schema，计数不动；check:spec-parsed-alias绿。两个键都无.default()/.transform()，不影响任何 isomorphism pin。changeset：
@objectstack/specminor（additive 声明，此前 parse 通过的一切仍然通过）。合入 main 时的一处联合失效（已修，记录在案）
merge
origin/main后content/docs/references/ui/component.mdx出现第二处 diff：main 的 inline-shape depth budget 改了嵌套形状的渲染方式，我 merge 前生成的产物和 main 的生成器文本合并干净、语义联合错误（PageTabsProps.items[].visibleWhen我这边展开、main 那边收敛）。已按合并后的生成器重新生成，现在对 main 的 delta 恰好只有本 PR 新增的两行。另有一处 §9 陈旧产物：merge 后只重建了 spec，
packages/lint的 4 条validate-expressions用例（#6290/#6584）报红，重建@objectstack/formula后全绿 —— 不是本改动引起的，记录以免下一位重新诊断。范围
⛔ 未动 objectui renderer（它已兑现）。⛔ 未动其它 element（B 案范围，见 #6590）。⛔ 未动
content/docs/releases/。Generated by Claude Code