feat(overlays): add managed overlay package

2026-09-28 23:13:44 +08:00
parent bca874fd30
commit 0ec968c344
34 changed files with 2340 additions and 0 deletions
@@ -0,0 +1,32 @@
+---
+title: 概览
+description: 使用统一 API 编排应用中的临时浮层。
+order: 1
+toc:
+  - id: package-role
+    title: 包的职责
+  - id: supported-overlays
+    title: 支持的浮层
+  - id: design-boundary
+    title: 设计边界
+---
+
+## 包的职责 {#package-role}
+
+`@workspace/overlays` 是基于 Base UI handle 和 `@workspace/ui` 的异步浮层编排层。业务代码通过 `openAlert()`、`openModal()` 等原子函数发起交互，不需要分别维护 `open` 状态。
+
+每种能力都使用独立子路径和 Host，例如 `@workspace/overlays/modal` 只包含 Modal 所需实现。`OverlayScope` 按需创建已经使用的 feature channel，不会预先构造所有 Base UI handle。同类请求按顺序显示，不会覆盖仍在等待的 Promise。
+
+## 支持的浮层 {#supported-overlays}
+
+- `alert`：等待用户确认消息。
+- `confirm`：返回 `true` 或 `false`。
+- `prompt`：返回输入字符串，取消时返回 `null`。
+- `modal`：居中的自定义内容浮层。
+- `sheet`：从页面边缘进入的面板。
+- `drawer`：支持拖动、方向和吸附点的面板。
+- `toast`：复用 Base UI toast manager 的通知、更新和 Promise 状态。
+
+## 设计边界 {#design-boundary}
+
+这个包负责 Scope、请求队列、Promise 结算和标准结构，不复制底层 UI primitives。根入口只导出 Scope 能力；具体 UI 从 `/alert`、`/modal`、`/sheet` 等子路径导入，以保留明确的 tree-shaking 边界。