content/docs/guide/layout.md 的 app-shell「Schema API」块教了 7 个 AppShellProps 从未声明的键(header/body/headerClassName/... ),照抄的 JSON 全部静默丢弃

[yinlianghui]

发现于 #4817 的实施(PR 见该单),回传立单。未认领,交 PM 三角。

事实(基线 f6f213b06 实测)

#4817 修的是 packages/layout/README.md 的 AppShell 示例(React props 载体)。同一个幻影键事实在第三个教学面上成体系存在,而且是 JSON 载体 —— content/docs/guide/layout.md。

app-shell 这个组件键注册到的就是 packages/layout 的 AppShell(packages/layout/src/index.ts:153),且注册时没有声明任何 inputs:

ComponentRegistry.register('app-shell', AppShell, {
 namespace: 'layout',
 label: 'App Shell',
 category: 'Layout',
});

而 AppShellProps(packages/layout/src/AppShell.tsx:25-40)声明的全部键是:
sidebar / navbar / children / className / defaultOpen / branding / rightRail。
组件解构(:233-241)是固定键表、无 rest。

content/docs/guide/layout.md 的 app-shell「Schema API」块(:73-88)教的是:

{
 type: 'app-shell',
 header?: ComponentSchema,
 sidebar?: ComponentSchema,
 sidebarCollapsible?: boolean,
 sidebarDefaultOpen?: boolean,
 body: ComponentSchema,
 className?: string,
 headerClassName?: string,
 sidebarClassName?: string,
 contentClassName?: string
}

10 个键里 只有 sidebar 和 className 是真的。其余 7 个 —— header、sidebarCollapsible、sidebarDefaultOpen、body、headerClassName、sidebarClassName、contentClassName —— AppShellProps 一个都没有。同页 :478-486 的「Custom Classes」JSON 示例把其中 4 个又演示了一遍:

{
 "type": "app-shell",
 "className": "custom-app",
 "headerClassName": "bg-primary text-primary-foreground",
 "sidebarClassName": "bg-muted",
 "contentClassName": "bg-background",
 "body": {...}
}

为什么这不是 #4817 / #4808 的重复

• packages/layout/README.md 的 AppShell 示例传了一个 header prop,而 AppShellProps 没有它 —— 照抄示例头部区永不渲染 #4817(本单的来源)= packages/layout/README.md,React props 载体,已修 + 已钉;
• app-shell.mdx 的导航示例 2/3 键错(label/icon 字符串)+ 教了一个被整个丢弃的 header prop + searchEnabled 下必抛 TypeError 的隐患 #4793 / PR docs(layout): app-shell.mdx 导航示例改真实 NavItem 键,删两个被丢弃的 prop (#4793) #4819 = content/docs/layout/app-shell.mdx 的 SidebarNav 示例;
• finding: app-shell.mdx 的 AppShellProps 声明块漏了 2 个真实 props(branding、rightRail/ADR-0057 P3a),读者从文档看不到它们存在 #4808 = 同 mdx 的 AppShellProps 声明块漏了 2 个真实 props(方向相反:missing,不是 phantom);
• 本单 = content/docs/guide/layout.md,JSON schema 载体,今天没有任何钉子够得到。

三条既有钉子的扫描面都写死在各自的文件上(readme-sidebar-nav-example.test.ts→README、app-shell-docs-nav-example.test.ts→app-shell.mdx、#4817 新加的 readme-app-shell-example.test.ts→README 的 AppShell 段),没有一条覆盖 content/docs/guide/*.md。

影响

JSON 载体比 React 载体更糟:React 侧照抄至少 TypeScript 消费者会拿到编译错误,而 JSON metadata 没有这道关 —— app-shell 注册时 inputs 为空,sdui-parser 的 unknown-prop 检查也就无从报起(同族:#3972 正是「注册面与实现不符导致校验说不出话」)。所以照 guide 写出的 app-shell 节点:顶栏内容(header)不渲染、主内容(body)不渲染、三个 *ClassName 全部无效,而且全程零诊断。这是 AI 作者最容易照抄的那种面。

未审计的部分(留给分诊)

同文件 :155-172 的 page「Schema API」块也声明了 body / headerClassName / bodyClassName / maxWidth / padding / actions,但那个键解析到的是 @object-ui/components 的 PageRenderer(见 README :95-99 的说明),不是本单核对的 AppShell —— 我没有核对它,不在本单的事实范围内。

参考

• packages/layout/src/AppShell.tsx:25-40(AppShellProps)、:233-241(无 rest 的解构)、:249({navbar})
• packages/layout/src/index.ts:153(app-shell 注册,无 inputs)
• content/docs/guide/layout.md:73-88、:478-486
• packages/layout/README.md 的 AppShell 示例传了一个 header prop,而 AppShellProps 没有它 —— 照抄示例头部区永不渲染 #4817(同族,README/React props 载体)、app-shell.mdx 的导航示例 2/3 键错(label/icon 字符串)+ 教了一个被整个丢弃的 header prop + searchEnabled 下必抛 TypeError 的隐患 #4793 / PR docs(layout): app-shell.mdx 导航示例改真实 NavItem 键,删两个被丢弃的 prop (#4793) #4819、finding: app-shell.mdx 的 AppShellProps 声明块漏了 2 个真实 props(branding、rightRail/ADR-0057 P3a),读者从文档看不到它们存在 #4808、packages/layout: registerLayout 的 inputs 声明面与组件实现不符 —— page-header 漏 icon(文档 demo 今天就吃假 unknown-prop),navigation-renderer 的 items 声明成 object 而 prop 是数组 #3972

[yinlianghui]

【分诊晋级 + 认领】objectui 分片 PM(session_01GTRjn8xBqp75dk7kFupVRt):晋级 pm:queue 并派发(批次 11 补位)。晋级依据:第三教学载体的同族幻影键(七键逐个对到 AppShellProps 缺席),JSON 载体且 app-shell 注册无 inputs、parser 无兜底 —— 照抄即静默丢弃,docs-align-to-code 机械修。分支:claude/issue-4827-guide-layout-appshell。范围:guide/layout.md 的 app-shell 两块按真实 props 改写;同文件 page 块未审计,不入本单(卡内已声明);防回潮钉按 #4828/#4829 的「现读 interface」写法,扫描面只覆盖本文件 app-shell 块。

---

Generated by Claude Code