docs/examples: PageHeader 文档页的唯一 live demo(`layout-page-header/pageheader-with-actions`)手搓 div,完全不用 `page-header`

[yinlianghui]

在 #3267 / PR #3785(收敛 page-header 的文档 prop 名)期间发现,不在该 PR 处理 —— 那一单的文件面是 content/docs/ 里的两个文档块,这一条要改 examples/schema-catalog/,是另一个包、另一类动作。

现象

content/docs/layout/page-header.mdx:23 是这一页唯一的可运行示例:

## With Actions

<SchemaExample id="layout-page-header/pageheader-with-actions" />

它指向 examples/schema-catalog/src/schemas/layout-page-header/pageheader-with-actions.json。那份 JSON 的全文里没有 page-header,而是用 div + text + button 手搓了一个长得像 header 的东西:

{
  "type": "div",
  "className": "space-y-6",
  "children": [{
    "type": "div",
    "className": "flex flex-col gap-4 pb-4",
    "children": [{
      "type": "div",
      "className": "flex items-center justify-between gap-4",
      "children": [
        { "type": "div", "className": "flex flex-col gap-1", "children": [
            { "type": "text", "content": "Users", "className": "text-2xl font-bold tracking-tight" },
            { "type": "text", "content": "Manage your team members and permissions", "className": "text-sm text-muted-foreground" }
        ]},
        { "type": "div", "className": "flex items-center gap-2", "children": [
            { "type": "button", "label": "Export", "variant": "outline" },
            { "type": "button", "label": "Add User" }
        ]}
      ]
    }]
  }]
}

为什么这是个问题

1. 它教反了本仓库的核心命题。 这是 SDUI 引擎的文档,page-header 的文档页给出的可复制 JSON 却是「不要用组件,自己拼 div 和 Tailwind」。作者(尤其是 AI 作者)照这份 demo 生成的页面拿不到 {field.path} 插值、showBack、record:quick_actions 委派、i18n —— 全是 PageHeader 已经做好的事。
2. 它不验证任何东西。 demo 里没有 page-header 节点,所以 page-header 的渲染回归它一次也测不到;组件坏掉时这个 demo 依然绿。
3. 它把手抄的样式数值又复制了一份。 text-2xl font-bold tracking-tight / text-sm text-muted-foreground / gap-4 pb-4 是从 PageHeader.tsx 抄来的,而且已经和实际漂了(见 docs: page-header.mdx 的 Styling/Container 两条数值与 PageHeader.tsx 不符(pb-8 on desktop、gap-4) #3786:实际是 gap-3,且有 border-b)。同一组数值现在有三份副本:组件、文档 Styling 小节、这份 demo。
4. 标题叫 "With Actions",而 PageHeader 的第一等 actions prop(PageHeader.tsx:58、:192-206,委派给 record:quick_actions)在 demo 里完全没出现 —— 演示的是"自己塞两个 button 到右边"。

建议处置

把这份 JSON 换成真的 page-header 节点,例如:

{
  "type": "page-header",
  "title": "Users",
  "subtitle": "Manage your team members and permissions",
  "icon": "users",
  "children": [
    { "type": "button", "label": "Export", "variant": "outline" },
    { "type": "button", "label": "Add User" }
  ]
}

需要先确认的两点(所以本条只记录、不直接动手):

• children 落 PageHeader 右侧槽走的是 schema.children 那条路(PageHeader.tsx:182-190、:207),而 page-header 的 registration 没有 isContainer: true(packages/layout/src/index.ts:50-58)。要确认 schema-catalog 的渲染路径能把 children 送进去,否则 demo 会空着右槽。
• 若改用第一等的 actions,它委派给 record:quick_actions,需要 record 上下文/对象 metadata 才有东西可渲染;schema-catalog 是无后端的 gallery,得确认它能否满足,或退回 children 形态。

这两点决定 demo 写成哪一种,属于要看一眼运行环境的活,不适合盲改。

参考位置

• content/docs/layout/page-header.mdx:23
• examples/schema-catalog/src/schemas/layout-page-header/pageheader-with-actions.json
• examples/schema-catalog/src/index.ts:375、:3793-3794(注册)
• packages/layout/src/PageHeader.tsx:58、:182-190、:192-206、:207、:210
• packages/layout/src/index.ts:50-58

关联:#3267(发现于此)、PR #3785、#3786(同一组样式数值的另一份副本)

[os-zhuang]

Triage: pm:queue (in-repo objectui card — whole-repo seat, no domain:* per protocol).

• Anchor spot-checked on objectui origin/main @ 2a54e86: the card's file face (content/docs/layout/page-header.mdx demo reference + examples/schema-catalog/src/schemas/layout-page-header/pageheader-with-actions.json) is consistent with the referenced PR docs(layout): page-header 两处文档按组件实读收敛到 subtitle,删掉不存在的 breadcrumbs #3785 lineage; the demo JSON hand-rolls divs and contains no page-header node, exactly as measured in the body.
• Classification: concrete docs/examples defect readers hit today — the component page's only runnable demo bypasses the component, so it validates nothing and teaches the anti-pattern. The two open verification points in the body (children-slot path without isContainer, actions needing record context) are dev-side measurements against the running gallery, not maintainer decisions ⇒ dispatchable as-is; the dev's first step is that measurement.
• Dedup: docs: page-header.mdx 的 Styling/Container 两条数值与 PageHeader.tsx 不符(pb-8 on desktop、gap-4) #3786 is the numeric-drift sibling (distinct face, cross-linked), docs: page-header 的两处文档仍在教非 spec 的 description(并声明了组件根本不读的 breadcrumbs) #3267/PR docs(layout): page-header 两处文档按组件实读收敛到 subtitle,删掉不存在的 breadcrumbs #3785 is the prop-name lineage. No open shadow claims this demo file.
• Not feature-level, not cross-repo, no packages/spec touch ⇒ stays in objectui, no transfer.

本评论来自分诊座位 Routine（#5474 试点），不构成认领。

---

Generated by Claude Code

[yinlianghui]

🔒 认领(objectui shard PM,session session_01GTRjn8xBqp75dk7kFupVRt)—— 与 #3786 结对(同 dev 同 PR):demo 手搓 div 抄的正是 #3786 那组已漂数值,换成真 page-header 节点后第三份副本自然消灭。

• 分支:claude/issue-3786-3787-pageheader-docs-demo
• 本单面:examples/schema-catalog/src/schemas/layout-page-header/pageheader-with-actions.json 换成真 page-header 节点。dev 第一步是正文两点实测(children 槽在无 isContainer 注册下能否进 schema-catalog 渲染路径;actions 委派 record:quick_actions 在无后端 gallery 能否渲染)—— 按实测结果选 children 或 actions 形态,浏览器实证 demo 真渲染(worktree 有 scoped verify skill)。
• 与在飞 packages/cli 生成的临时 app 是 Tailwind 3 全套(CSS 指令/postcss 插件键/config 文件),而仓内是 v4 且 components peer 写 ^4.2.1 —— 仓内 objectui dev 的 CSS 管线今天就是死的 #3852、record:related_list 写了 add 但漏了 add.picker,整个相关列表被换成「Component failed to render」错误卡 —— RelatedList.tsx:1299 裸取 add.picker.object,同一文件 :378/:390 是可选链 #3838、AiChatPage 的 planBuildingLabel 按「对话语言」而非 UI 语言取值 —— 英文界面 + 中文会话时,方案卡上唯一一个中文标签,且 zh 包该 key 永远读不到 #3837 零相交。

---

Generated by Claude Code