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

发现于 #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