feat(spec): 登记 ADR-0087 D2 conversion page-header-subtitle-alias(description → subtitle) - #5509
Merged
Conversation
…as` (#4827) page-header 节点 `properties.description` → canonical `subtitle`,protocol 17 live window。objectui 的 kebab 遗留别名与协议 canonical 键对同一个「页面副标题」 概念声明了两套 authorable 拼写,消费端用裸 `subtitle ?? description` 兜底 (PD #12)。不能走直接删路线:该别名的全部理由是仓外消费者 schema,删读会静默 丢副标题。改为在加载期改写,declared / loud / tested / expiring。 - `mapPageComponents` 加入 `conversions/walk.ts`(copy-on-write,region 级) - 条目 + fixture 落 `conversions/registry.ts`,并登记进 D3 链 step 17 - 覆盖 kebab `page-header` 与 canonical `page:header` 两种拼写;不改写 type - canonical 已在场时不改写、不发通知(照 `flow-node-crud-object-alias` 惯例) - 重生成 spec-changes.json / protocol-upgrade-guide.md Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018fxLGQdatPbBUvCgiVxg6D
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 109 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
This was referenced Aug 5, 2026
[移交自 objectui] 登记 ADR-0087 D2 conversion 条目
page-header-subtitle-alias(description → subtitle)
#4827
Closed
os-zhuang
marked this pull request as ready for review
August 5, 2026 15:49
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
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 #4827
Unblocks objectstack-ai/objectui#3226
做了什么
按 ADR-0087 D2 登记 protocol 17 的 live window 条目
page-header-subtitle-alias:加载期把 page-header 节点properties上的description改写为 canonical 的subtitle,每次改写发一条结构化ConversionNotice。落地后 objectui 才能删掉PageHeader.tsx里的裸subtitle ?? description(PD #12)。packages/spec/src/conversions/walk.ts— 新增mapPageComponents(copy-on-write,region 级)。pages[].regions[].components[]之前没有共享 walker,protocol-15 的page-component-visibility-to-visibleWhen是就地展开的;新 walker 只被本条目使用,没有改动那条已发布的条目。packages/spec/src/conversions/registry.ts— 条目 + fixture。packages/spec/src/migrations/registry.ts— 登记进 D3 链 step 17(否则 chain-replay gate 直接红)。spec-changes.json+docs/protocol-upgrade-guide.md(guide 里这行显示live — protocol 17 loader accepts the old shape,即预期的姿态)。两个需要 reviewer 过目的判断
1. 两种拼写都转,但不改写
type。 匹配page-header(objectui kebab 遗留别名)与page:header(协议 canonical 类型)两种节点 —— 后者今天写description是直接被丢在地上(canonical 渲染器只读subtitle),同一个缺陷换个拼写而已,而PageComponentSchema.type是z.union([PageComponentType, z.string()]),两种拼写都能进到加载路径。本条目不把page-header改写成page:header:别名注册的存废是 objectui 的事,而且在开放命名空间上改写 type 正是flow-node-http-callout-rename要配冲突守卫的那一类动作。2. 胜负语义照抄惯例,没有发明。
subtitle已在场时不改写、不发通知、被遮蔽的description原样留下 —— 就是renameKey编码的房规,与flow-node-crud-object-alias的 fixture 注释一字不差(canonical already present → the shadowed alias is left alone)。另外只动 header 节点:description在同层其他组件上是活的已声明属性(element:text_input的辅助文本),fixture 里留了这个反向对照。没有 schema 键被移除(
description从未在PageHeaderProps上声明过),所以不需要 tombstone,check:authorable-surface也保持绿。先证红(方向在跑之前就写下了)
两个场景分开做,因为它们证明的不是同一件事:
场景 A —— 摘掉注册(从
CONVERSIONS_BY_MAJOR[17]移除,实现还在):6 红 —— D3 两条 registry-integrity(every step references only real conversion ids、a graduated conversion belongs to the step for its own major)+ 我这 11 条里的 4 条;check:spec-changes也红。测试总数 177 → 175:逐条 fixture 测试与 chain-replay 测试是for (const conversion of ALL_CONVERSIONS)驱动的,条目一摘它们直接消失而不是变红 —— 典型的「因为什么都没产生所以绿」,它们不是本次的见证者。场景 B —— 掏空
apply()(注册留着):6 红 —— fixture pair + chain-replay + 我那 4 条断言改写的;总数仍是 177。但check:spec-changes保持绿:登记完整性 gate 钉的是「这条记录在不在」,不是「它干不干活」。两个 gate 家族各管一半,谁也替代不了谁。一处预测报错、如实记下:场景 A 我原本预测「我加的 11 条全红」,实测只红了 4 条。另外 7 条是「什么都没发生」型断言(不改 type、遮蔽时不动、幂等、copy-on-write)与两条独立的 schema pin —— 规则死掉时它们照样绿。它们是守卫,不是见证者,这个区分不该被模板抹平。
验证
按消费半径(而非改动包)扫了 fixture:全仓 grep
page:header/page-header,没有任何 fixture 让 header 节点带description,所以这条新规则不会把别的包的 fixture 判红 —— 与 issue 里「仓内零命中」的事实一致。packages/lint首跑 10 个文件红,是新 worktree 里@objectstack/formula/@objectstack/sdui-parser没构建(AGENTS.md §9 的陈旧产物陷阱),pnpm --filter '@objectstack/lint^...' build之后全绿,与本改动无关。一处顺带记录(不在本 PR 修)
本条目的
surface是page.component.page-header.description,叶名description因此进入了build-schemas.ts检查 (b) 的匹配词表 —— 那个检查按叶名endsWith匹配,所以此后任何X:description键被 tombstone 时都会被判为「已登记迁移」。这正是 #4659 记录的既有缺陷(不是本 PR 引入的机制),已在该 issue 下留言登记,没有另开重复单。Generated by Claude Code