docs: expand panel collection API docs

docs/api/XCEngine/Editor/panels/PanelCollection/Attach-Detach-And-Clear.md

@@ -0,0 +1,46 @@
+# PanelCollection Attach / Detach / Clear
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `method group`
+
+**源文件**: `editor/src/panels/PanelCollection.h`
+
+## 签名
+
+```cpp
+void AttachAll();
+void DetachAll();
+void Clear();
+```
+
+## 作用
+
+统一管理 collection 内所有面板的 attach / detach 生命周期，以及最终容器清空。
+
+## 当前实现行为
+
+### `AttachAll()`
+
+- 按容器正序遍历所有面板，并调用 `panel->OnAttach()`。
+
+### `DetachAll()`
+
+- 按容器逆序遍历所有面板，并调用 `panel->OnDetach()`。
+- 这意味着当前拆除顺序与构造顺序相反，适合让后创建的 UI 元素先释放。
+
+### `Clear()`
+
+- 直接清空内部 `std::vector<std::unique_ptr<Panel>>`。
+- 当前不会自动补做 `DetachAll()`，因此通常应在上层先完成 detach 再 clear。
+
+## 设计含义
+
+- `DetachAll()` 的逆序行为是当前实现里很关键的生命周期细节。
+- `Clear()` 与 `DetachAll()` 分开，也让上层能显式控制拆除时机。
+
+## 相关文档
+
+- [PanelCollection](PanelCollection.md)
+- [Context And Emplace](Context-And-Emplace.md)
+- [EditorWorkspace](../../Core/EditorWorkspace/EditorWorkspace.md)

docs/api/XCEngine/Editor/panels/PanelCollection/Context-And-Emplace.md

@@ -0,0 +1,52 @@
+# PanelCollection Context And Emplace
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `method group`
+
+**源文件**: `editor/src/panels/PanelCollection.h`
+
+## 签名
+
+```cpp
+IEditorContext* GetContext() const;
+void SetContext(IEditorContext* context);
+
+template <typename TPanel, typename... Args>
+TPanel& Emplace(Args&&... args);
+```
+
+## 作用
+
+管理 `PanelCollection` 持有的共享 `IEditorContext`，并把新面板构造进容器。
+
+## 当前实现行为
+
+### `GetContext()`
+
+- 返回当前缓存的上下文指针。
+
+### `SetContext(context)`
+
+- 直接把 `m_context` 更新为传入值。
+- 当 `context == nullptr` 时只更新内部字段，不会继续向面板补发。
+- 当 `context` 有效时，会遍历当前所有面板：
+  - 仅对尚未持有上下文的面板调用 `panel->SetContext(m_context)`
+
+### `Emplace<TPanel>(...)`
+
+- 要求 `TPanel` 必须继承自 [Panel](../Panel/Panel.md)。
+- 内部通过 `std::make_unique<TPanel>(...)` 构造新面板。
+- 若当前 collection 已持有上下文，会在入容器前先把上下文注入该面板。
+- 最终把面板放进 `std::vector<std::unique_ptr<Panel>>`，并返回具体类型引用。
+
+## 设计含义
+
+- `PanelCollection` 当前没有复杂 DI 容器，`IEditorContext*` 就是共享服务入口。
+- `Emplace(...)` 保证了“先建对象，再按需补上下文，再登记到容器”的顺序。
+
+## 相关文档
+
+- [PanelCollection](PanelCollection.md)
+- [Attach / Detach / Clear](Attach-Detach-And-Clear.md)
+- [Update / DispatchEvent / Render](Update-DispatchEvent-And-Render.md)

docs/api/XCEngine/Editor/panels/PanelCollection/PanelCollection.md

@@ -14,11 +14,9 @@
 
 它提供：
 
-- `SetContext()` 给全部面板注入上下文
-- `Emplace<TPanel>()` 构造并注册新面板
-- `AttachAll()` / `DetachAll()`
-- `UpdateAll()` / `DispatchEvent()` / `RenderAll()`
-- `Clear()`
+- [Context And Emplace](Context-And-Emplace.md)
+- [Attach / Detach / Clear](Attach-Detach-And-Clear.md)
+- [Update / DispatchEvent / Render](Update-DispatchEvent-And-Render.md)
 
 ## 当前实现说明
 

docs/api/XCEngine/Editor/panels/PanelCollection/Update-DispatchEvent-And-Render.md

@@ -0,0 +1,47 @@
+# PanelCollection Update / DispatchEvent / Render
+
+**命名空间**: `XCEngine::Editor`
+
+**类型**: `method group`
+
+**源文件**: `editor/src/panels/PanelCollection.h`
+
+## 签名
+
+```cpp
+void UpdateAll(float dt);
+void DispatchEvent(void* event);
+void RenderAll(const Panel* skipPanel = nullptr);
+```
+
+## 作用
+
+把逐帧更新、事件转发和面板渲染统一分发给 collection 中的全部面板。
+
+## 当前实现行为
+
+### `UpdateAll(dt)`
+
+- 按容器正序遍历所有面板，并调用 `panel->OnUpdate(dt)`。
+
+### `DispatchEvent(event)`
+
+- 按容器正序遍历所有面板，并调用 `panel->OnEvent(event)`。
+- 当前不做事件消费短路，所有面板都会收到这次转发。
+
+### `RenderAll(skipPanel)`
+
+- 按容器正序遍历所有面板。
+- 若 `panel.get() == skipPanel`，会跳过该面板。
+- 其余面板统一调用 `panel->Render()`。
+
+## 设计含义
+
+- `skipPanel` 当前主要用于避免某个特殊面板在“chrome / overlay 已单独绘制”时被重复渲染。
+- 该容器本身不区分停靠面板、浮动面板或后台面板，只负责顺序调度。
+
+## 相关文档
+
+- [PanelCollection](PanelCollection.md)
+- [Context And Emplace](Context-And-Emplace.md)
+- [EditorWorkspace](../../Core/EditorWorkspace/EditorWorkspace.md)