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,40 @@
+---
+title: Configuration and effective layout
+description: Manage controlled configuration, persistent preferences, and automatic region resolution.
+order: 20
+toc:
+  - id: controlled
+    title: Controlled and uncontrolled
+  - id: effective
+    title: Effective layout
+  - id: persistence
+    title: Persistence
+---
+
+## Controlled and uncontrolled {#controlled}
+
+Without `layout`, `AppLayout` owns its state:
+
+```tsx
+<AppLayout defaultLayout={{ sidebarOpen: false }} sidebar={NavigationSidebar}>
+  <RouterOutlet />
+</AppLayout>
+```
+
+After supplying `layout`, the caller must save each new snapshot from `onLayoutChange`:
+
+```tsx
+<AppLayout layout={layout} onLayoutChange={setLayout} aside={AssistantPanel}>
+  <RouterOutlet />
+</AppLayout>
+```
+
+## Effective layout {#effective}
+
+Configuration stores user intent, while the effective layout controls the current rendering. For example, `asideOpen` can remain `true` while a missing Aside slot or `asideEnabled: false` prevents the Aside from rendering. When `sidebarCollapsible` is `false`, the Sidebar remains visible even if the stored `sidebarOpen` value is `false`.
+
+Header and Footer starts follow the same principle. `"sidebar"` only takes effect while both the Rail and Sidebar are visible; otherwise it moves inward to `"content"`.
+
+## Persistence {#persistence}
+
+The effective layout never writes back into configuration, so temporarily missing regions do not clear user preferences. An application can persist the complete `LayoutConfig` through `@workspace/preferences` in `onLayoutChange`, then supply it through `layout` when loading.