chore: sync workspace state

docs/api/XCEngine/Editor/UI/UI.md

@@ -4,47 +4,106 @@
 
 **类型**: `submodule`
 
-**描述**: 编辑器 ImGui 基础设施、主题、控件与面板绘制辅助层。
+**描述**: 编辑器基于 Dear ImGui 的 UI 基础设施层，负责会话、主题 token、面板 chrome、树视图、属性布局和通用控件封装。
 
 ## 概述
 
-`UI` 子模块当前内容很多，但核心方向很清楚：
+`XCEngine::Editor::UI` 不是单个 widget 库，而是一组逐层叠加的编辑器 UI 基建。它的目标是把 Dear ImGui 这种非常自由、非常底层的即时模式 API 收束成一套可维护的“编辑器内建控件层”。
 
-- 维护 ImGui 会话与布局文件
-- 封装统一视觉主题
-- 提供属性面板、工具栏、菜单、场景状态等 UI 辅助
+当前源码里，这一层大致可以分成四层：
 
-已文档化的核心页面：
+1. **会话与后端层**
+   负责 ImGui 上下文、ini 持久化、后端桥接和纹理描述符分配。
+2. **主题与设计 token 层**
+   负责颜色、尺寸、间距、dock host 风格与常用视觉常量。
+3. **chrome 与布局层**
+   负责面板窗口、工具栏、树视图、splitter、divider、属性行布局和自定义 dock 标签栏。
+4. **语义化控件层**
+   负责属性网格、资产卡片、面包屑、弹窗、组件折叠段和各种编辑器专用小部件。
 
-- [ImGuiSession](ImGuiSession/ImGuiSession.md)
-- [ImGuiBackendBridge](ImGuiBackendBridge/ImGuiBackendBridge.md)
-- [BaseTheme](BaseTheme/BaseTheme.md)
-- [StyleTokens](StyleTokens/StyleTokens.md)
-- [Core](Core/Core.md)
-- [PanelChrome](PanelChrome/PanelChrome.md)
-- [Widgets](Widgets/Widgets.md)
-- [PopupState](PopupState/PopupState.md)
-- [ScalarControls](ScalarControls/ScalarControls.md)
-- [VectorControls](VectorControls/VectorControls.md)
-- [PropertyGrid](PropertyGrid/PropertyGrid.md)
-- [DockHostStyle](DockHostStyle/DockHostStyle.md)
-- [ConsoleFilterState](ConsoleFilterState/ConsoleFilterState.md)
-- [ConsoleLogFormatter](ConsoleLogFormatter/ConsoleLogFormatter.md)
-- [SceneStatusWidget](SceneStatusWidget/SceneStatusWidget.md)
-- [AboutEditorDialog](AboutEditorDialog/AboutEditorDialog.md)
+这类分层方式非常接近商业级游戏引擎编辑器的组织方式。原因很简单：如果每个面板都直接拼原始 ImGui 调用，代码很快就会变成不可维护的样式杂糅体；而先建设统一 UI 层，后续任何面板重构、主题调整和交互升级都会容易很多。
 
-`UI/UI.h` 本身只是聚合入口，真正值得阅读的是这些分层 helper：
+## 聚合头文件
 
-- `ImGuiSession + ImGuiBackendBridge` 负责上下文与后端绑定
-- `BaseTheme + StyleTokens` 负责视觉规范
-- `Core + PanelChrome + Widgets` 负责通用交互壳层
-- `ScalarControls + VectorControls + PropertyGrid` 负责 Inspector 表单体验
+**源文件**: `editor/src/UI/UI.h`
 
-这样拆分的好处，是把 Dear ImGui 容易失控的即时模式代码收束成一套可复用部件库。
+`UI.h` 当前是一个标准的 umbrella header。它的职责是把 Editor UI 常用 helper 聚合到同一个入口，而不是声明新的运行时类型。
+
+因此这页文档直接承担 `UI.h` 的说明职责，不再额外创建一个重复的类型页。
+
+## 当前架构重点
+
+结合当前 `editor/src/UI/**` 与最近一次 Editor UI 重构，以下几层是现在最值得读的核心：
+
+- `ImGuiSession + ImGuiBackendBridge`
+  管理 ImGui 上下文、DPI、SRV 描述符与窗口后端对接。
+- `BaseTheme + StyleTokens + DockHostStyle`
+  管理设计 token 和 dock host 外观，是全局视觉风格的起点。
+- `Core + DividerChrome + SplitterChrome + DockTabBarChrome + PanelChrome`
+  管理窗口 chrome、底边线、拖拽分隔条与自定义 dock 标签栏。
+- `TreeView + BuiltInIcons`
+  管理层级树 / 目录树的共享节点表现与图标前缀。
+- `PropertyLayout + ScalarControls + VectorControls + PropertyGrid`
+  管理 Inspector 的属性布局、标量控件、向量控件和高层属性编辑入口。
+- `Widgets + PopupState + SceneStatusWidget + AboutEditorDialog`
+  提供更接近编辑器业务语义的通用 widget。
+
+这次重构里，`TreeView`、`PropertyLayout`、`BuiltInIcons` 和 `DockTabBarChrome` 是最明显的新基础设施，它们共同把原先分散在具体面板中的 UI 技巧沉淀成了复用层。
+
+## 设计说明
+
+如果把它和 Unity 一类成熟编辑器对照，可以把 `Editor::UI` 理解成“编辑器内部控件系统”，而不是游戏运行时 UI 框架：
+
+- 它面向工具开发，不面向游戏内 HUD。
+- 它可以为编辑器体验服务而使用较强约束的 helper。
+- 它允许把某些风格、布局和交互策略写死在共享层，以换取整个工具界面的统一性。
+
+这种设计的好处是：
+
+- 面板作者写的代码更接近业务语义，而不是样式拼装。
+- 主题、间距、树视图和 Inspector 布局能在全局范围内保持一致。
+- 面板之间可以共享拖拽、上下文菜单、资产卡片、树节点前缀等成熟模式。
+
+代价也很明确：
+
+- 当前 UI 层明显偏 Editor 私有实现，不是面向外部插件的稳定 ABI。
+- 很多 helper 仍然是 header-only inline 形式，接口演化速度会比较快。
+- 当前实现强依赖 Windows + D3D12 + Dear ImGui 的编辑器运行路径。
+
+## 头文件
+
+- [AboutEditorDialog](AboutEditorDialog/AboutEditorDialog.md) - `AboutEditorDialog.h`，关于对话框相关 UI。
+- [BaseTheme](BaseTheme/BaseTheme.md) - `BaseTheme.h`，编辑器基础主题安装。
+- [BuiltInIcons](BuiltInIcons/BuiltInIcons.md) - `BuiltInIcons.h`，内置资源/对象图标系统。
+- [ConsoleFilterState](ConsoleFilterState/ConsoleFilterState.md) - `ConsoleFilterState.h`，Console 过滤状态。
+- [ConsoleLogFormatter](ConsoleLogFormatter/ConsoleLogFormatter.md) - `ConsoleLogFormatter.h`，Console 日志格式化。
+- [Core](Core/Core.md) - `Core.h`，底层 ImGui helper 与 popup chrome 包装。
+- [DividerChrome](DividerChrome/DividerChrome.md) - `DividerChrome.h`，统一分隔线绘制。
+- [DockHostStyle](DockHostStyle/DockHostStyle.md) - `DockHostStyle.h`，dock host 风格压栈。
+- [DockTabBarChrome](DockTabBarChrome/DockTabBarChrome.md) - `DockTabBarChrome.h`，自定义 dock 标签栏。
+- [ImGuiBackendBridge](ImGuiBackendBridge/ImGuiBackendBridge.md) - `ImGuiBackendBridge.h`，ImGui 与 D3D12 之间的桥接层。
+- [ImGuiSession](ImGuiSession/ImGuiSession.md) - `ImGuiSession.h`，ImGui 会话生命周期。
+- [PanelChrome](PanelChrome/PanelChrome.md) - `PanelChrome.h`，面板窗口 / 工具栏 / 内容区 RAII 外壳。
+- [PopupState](PopupState/PopupState.md) - `PopupState.h`，延迟弹窗与目标型弹窗状态。
+- [PropertyGrid](PropertyGrid/PropertyGrid.md) - `PropertyGrid.h`，Inspector 级属性编辑入口。
+- [PropertyLayout](PropertyLayout/PropertyLayout.md) - `PropertyLayout.h`，属性行几何布局层。
+- [ScalarControls](ScalarControls/ScalarControls.md) - `ScalarControls.h`，标量属性控件。
+- [SceneStatusWidget](SceneStatusWidget/SceneStatusWidget.md) - `SceneStatusWidget.h`，场景状态部件。
+- [SplitterChrome](SplitterChrome/SplitterChrome.md) - `SplitterChrome.h`，分隔条交互与绘制。
+- [StyleTokens](StyleTokens/StyleTokens.md) - `StyleTokens.h`，Editor UI 设计 token 中心。
+- [TreeView](TreeView/TreeView.md) - `TreeView.h`，树视图共享基础设施。
+- [VectorControls](VectorControls/VectorControls.md) - `VectorControls.h`，向量属性控件。
+- [Widgets](Widgets/Widgets.md) - `Widgets.h`，资产卡片、面包屑、组件折叠段等通用 widget。
+
+## 当前实现边界
+
+- 这是 Editor 应用层 UI，不是运行时 `engine/include/XCEngine` 风格的公共引擎 API。
+- 当前很多接口仍然直接暴露 ImGui 类型，如 `ImDrawList`、`ImVec2`、`ImGuiID`。
+- 自定义 dock 标签栏、树视图和图标系统都明显面向当前编辑器产品形态，而不是通用 GUI 框架。
 
 ## 相关文档
 
-- [Editor 模块](../Editor.md)
-- [Application](../Application/Application.md)
-- [Platform](../Platform/Platform.md)
+- [Editor](../Editor.md)
+- [Layout](../Layout/Layout.md)
+- [ComponentEditors](../ComponentEditors/ComponentEditors.md)
 - [Editor Architecture And Workflow](../../../_guides/Editor/Editor-Architecture-And-Workflow.md)