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: Overview
+description: Coordinate temporary application overlays through one API.
+order: 1
+toc:
+  - id: package-role
+    title: Package role
+  - id: supported-overlays
+    title: Supported overlays
+  - id: design-boundary
+    title: Design boundary
+---
+
+## Package role {#package-role}
+
+`@workspace/overlays` is an asynchronous overlay orchestration layer built on Base UI handles and `@workspace/ui`. Application code starts interactions through atomic functions such as `openAlert()` and `openModal()` instead of owning separate `open` state.
+
+Every feature has its own subpath and Host. For example, `@workspace/overlays/modal` contains only the Modal implementation. An `OverlayScope` creates feature channels lazily instead of constructing every Base UI handle up front. Requests of the same kind are queued and never replace a Promise that is still pending.
+
+## Supported overlays {#supported-overlays}
+
+- `alert` waits until a message is acknowledged.
+- `confirm` returns `true` or `false`.
+- `prompt` returns the entered string, or `null` after cancellation.
+- `modal` displays centered custom content.
+- `sheet` displays a panel from a page edge.
+- `drawer` adds dragging, direction, and snap-point behavior.
+- `toast` reuses the Base UI toast manager for notifications, updates, and Promise states.
+
+## Design boundary {#design-boundary}
+
+The package owns scopes, request queues, Promise settlement, and standard structure without duplicating the underlying UI primitives. The root entry exports only scope capabilities; import concrete UI from subpaths such as `/alert`, `/modal`, and `/sheet` to preserve explicit tree-shaking boundaries.