docs: expand popup state API docs

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

@@ -0,0 +1,51 @@
+# DeferredPopupState
+
+**命名空间**: `XCEngine::Editor::UI`
+
+**类型**: `class`
+
+**源文件**: `editor/src/UI/PopupState.h`
+
+## 作用
+
+表示“下一帧打开一个 ImGui popup”的最小延迟打开状态。
+
+## 公开接口
+
+```cpp
+void RequestOpen();
+void ConsumeOpenRequest(const char* popupId);
+bool HasPendingOpenRequest() const;
+void Clear();
+```
+
+## 当前实现行为
+
+- `RequestOpen()`
+  - 只把内部 `m_openRequested` 设为 `true`
+  - 当前帧不会立刻调用 `ImGui::OpenPopup(...)`
+- `ConsumeOpenRequest(popupId)`
+  - 只有当存在待消费请求时才会调用 `ImGui::OpenPopup(popupId)`
+  - 成功消费后会把待开标志清回 `false`
+- `HasPendingOpenRequest()`
+  - 返回当前是否还保留未消费的打开请求
+- `Clear()`
+  - 只清空待开标志
+
+## 典型使用位置
+
+- `MainMenuActionRouter` 用它驱动 `Help -> About`
+- `InspectorActionRouter` 用它驱动 `Add Component`
+- `HierarchyActionRouter` 用它驱动层级空白区域或选项 popup
+- `AboutEditorDialog` 会在真正绘制前调用 `ConsumeOpenRequest(...)`
+
+## 设计含义
+
+- 这类 helper 的核心价值是把“请求打开 popup”和“实际调用 `ImGui::OpenPopup()` 的帧时机”分开。
+- 这样调用方不需要自己维护散落的布尔标志。
+
+## 相关文档
+
+- [PopupState](PopupState.md)
+- [TargetedPopupState](TargetedPopupState.md)
+- [AboutEditorDialog](../AboutEditorDialog/AboutEditorDialog.md)

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

@@ -0,0 +1,68 @@
+# InlineTextEditState
+
+**命名空间**: `XCEngine::Editor::UI`
+
+**类型**: `template class`
+
+**源文件**: `editor/src/UI/PopupState.h`
+
+## 签名
+
+```cpp
+template <typename ItemId, size_t BufferCapacity>
+class InlineTextEditState;
+```
+
+## 作用
+
+为列表项或树节点的“行内重命名”提供目标项、文本缓冲区和首帧聚焦状态。
+
+## 公开接口
+
+```cpp
+void Begin(ItemId itemId, const char* initialValue = "");
+bool IsActive() const;
+bool IsEditing(ItemId itemId) const;
+ItemId Item() const;
+bool ConsumeFocusRequest();
+void SetValue(const char* value);
+bool Empty() const;
+char* Buffer();
+const char* Buffer() const;
+constexpr size_t BufferSize() const;
+void Cancel();
+```
+
+## 当前实现行为
+
+- `Begin(itemId, initialValue)`
+  - 进入编辑态
+  - 记录当前目标项 id
+  - 把初始文本写入缓冲区
+  - 把 `m_focusRequested` 设为 `true`
+- `IsEditing(itemId)`
+  - 只有在当前处于活动编辑态且目标项匹配时返回 `true`
+- `ConsumeFocusRequest()`
+  - 第一次消费时返回 `true`，随后自动清零
+  - 适合驱动 `ImGui::SetKeyboardFocusHere()` 一类逻辑
+- `SetValue(...)`
+  - 用 `strcpy_s` 更新当前缓冲区
+- `Cancel()`
+  - 退出编辑态
+  - 清空目标项、文本缓冲区和待聚焦标志
+
+## 典型使用位置
+
+- `HierarchyPanel` 用 `InlineTextEditState<uint64_t, 256>` 保存实体重命名状态
+- `ProjectPanel` 用 `InlineTextEditState<std::string, 256>` 保存项目资源项重命名状态
+
+## 设计含义
+
+- 即时模式 UI 里，行内重命名最麻烦的通常是“哪一项正在编辑”和“进入编辑后只聚焦一次”。
+- 这个 helper 把这两件事一起封装了。
+
+## 相关文档
+
+- [PopupState](PopupState.md)
+- [HierarchyPanel](../../panels/HierarchyPanel/HierarchyPanel.md)
+- [ProjectPanel](../../panels/ProjectPanel/ProjectPanel.md)

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

@@ -12,19 +12,21 @@
 
 `PopupState.h` 当前包含四类非常实用的 UI 状态辅助类型：
 
-- `DeferredPopupState`
+- [DeferredPopupState](DeferredPopupState.md)
-- `TargetedPopupState<T>`
+- [TargetedPopupState<T>](TargetedPopupState.md)
-- `TextInputPopupState<BufferCapacity>`
+- [TextInputPopupState<BufferCapacity>](TextInputPopupState.md)
-- `InlineTextEditState<ItemId, BufferCapacity>`
+- [InlineTextEditState<ItemId, BufferCapacity>](InlineTextEditState.md)
 
 它们共同解决一个问题：把 ImGui 的即时模式弹窗交互变成可维护的状态机。
 
 ## 当前实现
 
-- `DeferredPopupState` 负责“下一帧打开弹窗”
+| 类型 | 作用 |
-- `TargetedPopupState<T>` 在打开弹窗的同时绑定一个目标对象
+|------|------|
-- `TextInputPopupState` 内置固定容量字符缓冲区，适合创建目录等对话框
+| [DeferredPopupState](DeferredPopupState.md) | 负责“下一帧打开弹窗”。 |
-- `InlineTextEditState` 适合 Hierarchy 中的行内重命名
+| [TargetedPopupState<T>](TargetedPopupState.md) | 在打开弹窗的同时绑定一个目标对象。 |
+| [TextInputPopupState<BufferCapacity>](TextInputPopupState.md) | 内置固定容量字符缓冲区，适合轻量文本输入 popup。 |
+| [InlineTextEditState<ItemId, BufferCapacity>](InlineTextEditState.md) | 适合 Hierarchy / Project 中的行内重命名。 |
 
 ## 设计说明
 
@@ -44,6 +46,10 @@
 ## 相关文档
 
 - [UI](../UI.md)
+- [DeferredPopupState](DeferredPopupState.md)
+- [TargetedPopupState](TargetedPopupState.md)
+- [TextInputPopupState](TextInputPopupState.md)
+- [InlineTextEditState](InlineTextEditState.md)
 - [ProjectActionRouter](../../Actions/ProjectActionRouter/ProjectActionRouter.md)
 - [HierarchyActionRouter](../../Actions/HierarchyActionRouter/HierarchyActionRouter.md)
 - [AboutEditorDialog](../AboutEditorDialog/AboutEditorDialog.md)

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

@@ -0,0 +1,65 @@
+# TargetedPopupState
+
+**命名空间**: `XCEngine::Editor::UI`
+
+**类型**: `template class`
+
+**源文件**: `editor/src/UI/PopupState.h`
+
+## 签名
+
+```cpp
+template <typename Target>
+class TargetedPopupState;
+```
+
+## 作用
+
+在延迟打开 popup 的同时，把一个目标对象或目标句柄绑定到该 popup 状态上。
+
+## 公开接口
+
+```cpp
+void RequestOpen(Target target);
+void ConsumeOpenRequest(const char* popupId);
+bool HasPendingOpenRequest() const;
+bool HasTarget() const;
+Target& TargetValue();
+const Target& TargetValue() const;
+void Clear();
+```
+
+## 当前实现行为
+
+- `RequestOpen(target)`
+  - 会把 `target` 移入 `m_target`
+  - 把 `m_hasTarget` 设为 `true`
+  - 再通过内部 `DeferredPopupState` 记录一次待开请求
+- `ConsumeOpenRequest(...)`
+  - 直接转发给内部 `DeferredPopupState`
+- `HasPendingOpenRequest()`
+  - 返回当前是否还存在未消费的 popup 打开请求
+- `HasTarget()`
+  - 返回当前是否已绑定有效目标
+- `TargetValue()`
+  - 返回当前绑定目标
+- `Clear()`
+  - 清空内部 popup 请求
+  - 把目标重置为 `Target{}`
+  - 把 `m_hasTarget` 设回 `false`
+
+## 典型使用位置
+
+- `HierarchyActionRouter` 用 `TargetedPopupState<GameObject*>` 维护实体右键菜单目标
+- `ProjectActionRouter` 用 `TargetedPopupState<AssetItemPtr>` 维护项目资源项上下文菜单目标
+
+## 当前实现边界
+
+- 目标对象的生命周期不由该类型管理。
+- 它只保存一个值或句柄，不做失效检测。
+
+## 相关文档
+
+- [PopupState](PopupState.md)
+- [DeferredPopupState](DeferredPopupState.md)
+- [ProjectActionRouter](../../Actions/ProjectActionRouter/ProjectActionRouter.md)

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

@@ -0,0 +1,64 @@
+# TextInputPopupState
+
+**命名空间**: `XCEngine::Editor::UI`
+
+**类型**: `template class`
+
+**源文件**: `editor/src/UI/PopupState.h`
+
+## 签名
+
+```cpp
+template <size_t BufferCapacity>
+class TextInputPopupState;
+```
+
+## 作用
+
+为单字段文本输入 popup 提供固定容量缓冲区和延迟打开状态。
+
+## 公开接口
+
+```cpp
+void RequestOpen(const char* initialValue = "");
+void ConsumeOpenRequest(const char* popupId);
+void SetValue(const char* value);
+void Clear();
+bool Empty() const;
+char* Buffer();
+const char* Buffer() const;
+constexpr size_t BufferSize() const;
+```
+
+## 当前实现行为
+
+- `RequestOpen(initialValue)`
+  - 先把初始值写入内部字符缓冲区
+  - 再通过内部 `DeferredPopupState` 记录待开请求
+- `ConsumeOpenRequest(...)`
+  - 转发给内部 popup 状态，在合适帧调用 `ImGui::OpenPopup(...)`
+- `SetValue(value)`
+  - 当传入非空且非空串时，使用 `strcpy_s` 写入缓冲区
+  - 否则会把缓冲区首字符置零
+- `Clear()`
+  - 当前只清空文本缓冲区
+  - 不会额外清掉内部 popup 请求状态
+- `Empty()`
+  - 通过检查首字符是否为 `'\0'` 判断内容是否为空
+- `Buffer()` / `BufferSize()`
+  - 供 `ImGui::InputText(...)` 一类 API 直接消费
+
+## 设计含义
+
+- 这个 helper 适合“打开 popup 后输入一段名字”的轻量对话框。
+- 它把常见的 `char buffer[N] + OpenPopup` 模式封装成可复用状态。
+
+## 当前实现边界
+
+- 容量是模板参数，调用方需要自己选择缓冲区大小。
+- 当前不提供校验、提交态或多字段表单状态。
+
+## 相关文档
+
+- [PopupState](PopupState.md)
+- [DeferredPopupState](DeferredPopupState.md)