docs: app-shell.mdx 三处声称 AppShell 自带 sidebar toggle / SidebarTrigger,但 packages/layout 的 AppShell 从不渲染它

发现于 #3914 的实现(分支 claude/issue-3914-appshell-docs-numbers,PR #3945),不在该 PR 处理 —— #3914 的判定面被钉在 app-shell.mdx:64 / :71 两处数值(header 高度、content padding),这一条是同一页里另一类断言(声称存在一个并不存在的 UI 元素),独立成卡。

在 origin/main @ ebb579dbb 核过。

现象

content/docs/layout/app-shell.mdx 三处把「sidebar 切换按钮」算作 AppShell 自身提供的东西:

:62(Header Bar 段)—— The header bar provides: 下第一条 - Sidebar toggle button
:106(Collapsible Sidebar 段)—— The sidebar can be toggled via: 下 - Hamburger menu button (always visible)
:251(Styling 段)—— - SidebarTrigger: Hamburger menu button,列在「The AppShell uses Tailwind CSS and Shadcn UI components」之下

实况:packages/layout/src/AppShell.tsx 里没有 SidebarTrigger,header 元素只渲染 {navbar}。

导入块(:2-6)只有三个:SidebarProvider、SidebarInset、Sidebar
header(:249-251)的唯一子节点是 {navbar}
git grep -c SidebarTrigger origin/main -- packages/layout/src → 0 命中(整个包都没有,不只是这个文件)
SidebarTrigger 的真实使用者在别处:packages/app-shell/src/layout/AppHeader.tsx、packages/app-shell/src/layout/UnifiedSidebar.tsx、packages/components/src/renderers/navigation/header-bar.tsx 等 —— 都不是 @object-ui/layout 的 AppShell

为什么值得记一笔

这不是数值漂移,而是能力归属错了:按文档直接用 @object-ui/layout 的 AppShell、期待「hamburger 按钮 always visible」的作者,会得到一个没有任何办法收起 sidebar 的外壳 —— 切换按钮得自己塞进 navbar 插槽,或者改用 packages/app-shell 那一套。Styling 段把 SidebarTrigger 列进「AppShell uses」更会让人以为它已经在树里了。

与 #3914 / #3786 / #3902 是同一家族(文档断言无法从文档自身验证),但这一条的修法不是换措辞而是判断意图:

建议处置(有一个小决策,故不自行动手)

两条路,选哪条不是文档层面能定的:

文档向代码对齐 —— 删掉/改写这三处,写明 toggle 需由使用者放进 navbar(并给一行示例),Styling 段的 SidebarTrigger 一项删掉。
代码向文档对齐 —— 认为「AppShell 自带 toggle」本来就是预期行为,在 header 里补一个 SidebarTrigger(那会改变现有使用者的 header 视觉,属产品决策)。

倾向 1(#3914 定的方向就是文档向代码对齐,且 packages/app-shell 已有自带 header/trigger 的成套实现,@object-ui/layout 的 AppShell 保持纯骨架是合理的分工),但请维护者定。

参考位置

content/docs/layout/app-shell.mdx:62、:106、:251
packages/layout/src/AppShell.tsx:2-6(导入)、:249-251(header)
对照实现:packages/app-shell/src/layout/AppHeader.tsx

关联:#3914(发现于此)、#3945、#3786 / #3902(同类假断言的先例)

Generated by Claude Code

Triage: needs-user-decision.

Classification: the defect (docs claim a capability the component does not have) is real and verified, but the fix is a fork the maintainer owns: (1) docs align to code — @object-ui/layout's AppShell stays a pure skeleton and the three doc claims are rewritten (toggle goes in the consumer's navbar slot), vs (2) code aligns to docs — AppShell grows a built-in SidebarTrigger, changing every existing user's header. Option 2 is a shipped-visual/product-semantics change, so this sits in the decision box rather than the queue. Filer's lean (option 1, consistent with docs: app-shell.mdx 的 Header Bar / Content Area 两处数值与 AppShell.tsx 不符(「64px / 4rem」实为 h-14=56px;「4 on mobile」实为 p-3,且 mobile 的 pb-20 未记) #3914's docs-align-to-code direction and packages/app-shell owning the full header/trigger implementation) reads correct to this seat as well — recommendation: 1.
Anchors verified on origin/main @ cb5e32d: content/docs/layout/app-shell.mdx:62 still lists "Sidebar toggle button"; git grep -c SidebarTrigger over packages/layout/src returns zero hits (the mdx is the only carrier).
Dedup: repo-scoped search for SidebarTrigger — only this card. docs: app-shell.mdx 的 Header Bar / Content Area 两处数值与 AppShell.tsx 不符(「64px / 4rem」实为 h-14=56px;「4 on mobile」实为 p-3,且 mobile 的 pb-20 未记) #3914 / PR docs(layout): app-shell 的 Header Bar / Content Area 两处数值按 AppShell.tsx 现状改写 (#3914) #3945 own the numeric drift on the same page, disjoint lines.
Per whole-repo-seat protocol, no domain:* label in this repo.

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

Generated by Claude Code

Maintainer ruling (2026-08-10, directed in session session_01BPWqbmEFU8gJepBJTHESXd): docs follow implementation.

Correct the three app-shell.mdx claims now — AppShell does not render a sidebar toggle / SidebarTrigger, and the docs must not promise it. If the toggle is wanted as product behavior, that is a separate enhancement card; documentation never leads implementation on a claim a truth-sweep can falsify.

needs-user-decision → pm:queue.

Generated by Claude Code

【分诊轮复核·晋级】座位 repo:objectui(session_01GTRjn8xBqp75dk7kFupVRt,2026-08-16):finding → pm:queue。复核实测(origin/main c252227):三处文档声称原样在(:60/:104/:250),packages/layout 零 SidebarTrigger(邻近词反查过),AppShell header 仍只渲染 {navbar}。

方向裁定(机械侧,留否决窗):文档对齐代码现状 —— 移除/改写三处错误声称(sidebar 内容与 toggle 均由使用者提供,文档写清这个分工);「AppShell 是否该自带 toggle」是产品增强,若维护者想要另立卡,本单不做代码。与 #3947(同包 AppShell.tsx dead import)结对同批派发、不同文件可同 dev。

Generated by Claude Code

【认领】objectui 分片 PM(session_01GTRjn8xBqp75dk7kFupVRt)批次 11 派发,os-dev 实施,与 #3947 结对同一 dev。分支:claude/issue-3946-appshell-docs-toggle。按维护者 2026-08-10 裁定执行:文档对齐实现,改写 content/docs/layout/app-shell.mdx 三处 toggle/SidebarTrigger 声称(现行 :60/:104/:250,以实读为准);「自带 toggle」若要另立增强卡由维护者定,本单零产品行为变更。热文件声明:本批独占 app-shell.mdx(#4793 同文件,待本单落地后再派)。

Generated by Claude Code

docs(layout): app-shell.mdx stops promising a sidebar toggle AppShell…

Navigation Menu

Repository navigation

docs: `app-shell.mdx` 三处声称 AppShell 自带 sidebar toggle / `SidebarTrigger`,但 `packages/layout` 的 AppShell 从不渲染它 #3946

现象

为什么值得记一笔

建议处置(有一个小决策,故不自行动手)

参考位置

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

docs: app-shell.mdx 三处声称 AppShell 自带 sidebar toggle / SidebarTrigger,但 packages/layout 的 AppShell 从不渲染它 #3946

Description

现象

为什么值得记一笔

建议处置(有一个小决策,故不自行动手)

参考位置

Activity

os-zhuang commented on Aug 9, 2026

os-zhuang commented on Aug 10, 2026

yinlianghui commented on Aug 16, 2026

yinlianghui commented on Aug 16, 2026

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

docs: `app-shell.mdx` 三处声称 AppShell 自带 sidebar toggle / `SidebarTrigger`,但 `packages/layout` 的 AppShell 从不渲染它 #3946