docs(layout): document app layout composition

2026-09-30 01:30:56 +08:00
parent ffda0b9099
commit 57d006a39b
10 changed files with 573 additions and 0 deletions
@@ -0,0 +1,67 @@
+---
+title: 概览
+description: 使用可选区域和可持久化配置构建应用级布局。
+order: 1
+toc:
+  - id: role
+    title: 包的职责
+  - id: regions
+    title: 布局区域
+  - id: config
+    title: 配置与 Hook
+---
+
+## 包的职责 {#role}
+
+`@workspace/layout` 提供路由无关的 `AppLayout`。它通过 CSS Grid 组合应用 Header、Navigation Rail、Sidebar、内容区、Aside 和 Footer，并根据实际可见区域自动计算有效网格。包不创建导航数据，不限制路由器，也不持久化用户偏好。
+
+在应用全局样式中导入 Tailwind 源：
+
+```css
+@import "@workspace/layout/globals.css";
+```
+
+## 布局区域 {#regions}
+
+```tsx
+import { AppLayout } from "@workspace/layout"
+
+export function Application() {
+  return (
+    <AppLayout
+      header={AppHeader}
+      rail={ActivityRail}
+      sidebar={NavigationSidebar}
+      aside={AssistantPanel}
+      footer={StatusBar}
+      defaultLayout={{ asideOpen: true }}
+    >
+      <RouterOutlet />
+    </AppLayout>
+  )
+}
+```
+
+`children` 是唯一必需的内容区。Sidebar 可以折叠，Aside 适合 AI、文档和检查器等辅助功能。Header 可以从 Rail、Sidebar 或内容区开始；Footer 可以从 Sidebar 或内容区开始。缺少前置区域时，起始位置会自动向内容区内移。
+
+## 配置与 Hook {#config}
+
+`layout` 接收 `Partial<LayoutConfig>`。提供它时使用受控模式；否则 `AppLayout` 通过 `defaultLayout` 初始化内部状态。区域组件可以调用 `useLayoutConfig`：
+
+```tsx
+import { useLayoutConfig } from "@workspace/layout"
+
+export function AppHeader() {
+  const { layout, toggleAside, toggleSidebar } = useLayoutConfig()
+
+  return (
+    <nav>
+      <button onClick={toggleSidebar}>Sidebar</button>
+      <button onClick={toggleAside}>Assistant</button>
+      <output>{layout.headerStart}</output>
+    </nav>
+  )
+}
+```
+
+临时隐藏或禁用区域只影响当前有效布局，不会覆盖 `LayoutConfig` 中保存的原始偏好，因此配置可以安全接入 `@workspace/preferences`。