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,73 @@
+---
+title: 自定义浮层示例
+description: 使用 UI 组件构建有返回值的 modal、sheet 和 drawer。
+order: 30
+toc:
+  - id: typed-modal
+    title: 类型化 Modal
+  - id: sheet
+    title: Sheet
+  - id: drawer
+    title: Drawer
+---
+
+## 类型化 Modal {#typed-modal}
+
+render callback 接收 `close` 和 `dismiss`。`close` 返回业务结果，`dismiss` 进入取消路径。
+
+```tsx
+import { openModal } from "@workspace/overlays/modal"
+import { Button } from "@workspace/ui/components/button"
+
+function PlanButton() {
+  async function choosePlan() {
+    const plan = await openModal<"free" | "pro">({
+      title: "选择方案",
+      description: "以后仍然可以修改。",
+      content: ({ close, dismiss }) => (
+        <div className="flex justify-end gap-2">
+          <Button variant="outline" onClick={dismiss}>
+            取消
+          </Button>
+          <Button onClick={() => close("free")}>免费版</Button>
+          <Button onClick={() => close("pro")}>专业版</Button>
+        </div>
+      ),
+    })
+
+    if (plan) updatePlan(plan)
+  }
+
+  return <Button onClick={choosePlan}>修改方案</Button>
+}
+```
+
+## Sheet {#sheet}
+
+```tsx
+import { openSheet } from "@workspace/overlays/sheet"
+
+await openSheet({
+  title: "筛选条件",
+  side: "right",
+  content: <ProductFilters />,
+})
+```
+
+Sheet 适合固定边缘面板。`side` 支持 `top`、`right`、`bottom` 和 `left`。
+
+## Drawer {#drawer}
+
+```tsx
+import { openDrawer } from "@workspace/overlays/drawer"
+
+await openDrawer({
+  title: "选择配送时间",
+  content: <DeliverySlots />,
+  showSwipeHandle: true,
+  snapPoints: [0.5, 1],
+  swipeDirection: "down",
+})
+```
+
+Drawer 适合触摸交互，可以配置滑动方向和 Base UI snap points。