docs(ui): expand bilingual component guides

2026-09-21 17:27:45 +08:00
parent fb985edb20
commit 4c61e79d0d
22 changed files with 1636 additions and 192 deletions
@@ -0,0 +1,113 @@
+---
+title: Overlays and positioning
+description: Compose Dialog and Popover with Base UI render semantics and the local AnchoredSurface.
+order: 12
+toc:
+  - id: dialog
+    title: Dialog
+  - id: popover
+    title: Popover
+  - id: anchored-surface
+    title: Continuous tail
+  - id: positioning
+    title: Custom positioning
+  - id: choosing-an-overlay
+    title: Choose an overlay
+---
+
+## Dialog {#dialog}
+
+```tsx
+import { Button } from "@workspace/ui/components/button"
+import {
+  Dialog,
+  DialogContent,
+  DialogDescription,
+  DialogFooter,
+  DialogHeader,
+  DialogTitle,
+  DialogTrigger,
+} from "@workspace/ui/components/dialog"
+
+export function ProfileDialog() {
+  return (
+    <Dialog>
+      <DialogTrigger render={<Button variant="outline" />}>
+        Edit profile
+      </DialogTrigger>
+      <DialogContent>
+        <DialogHeader>
+          <DialogTitle>Edit profile</DialogTitle>
+          <DialogDescription>Update your public information.</DialogDescription>
+        </DialogHeader>
+        <div>Form content</div>
+        <DialogFooter>
+          <Button type="submit">Save</Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}
+```
+
+`DialogContent` already includes the portal, overlay, and default close button. The title and description connect to the underlying accessibility attributes, so do not replace them with unstructured `div` elements.
+
+## Popover {#popover}
+
+```tsx
+import { Button } from "@workspace/ui/components/button"
+import {
+  Popover,
+  PopoverContent,
+  PopoverDescription,
+  PopoverTitle,
+  PopoverTrigger,
+} from "@workspace/ui/components/popover"
+
+;<Popover>
+  <PopoverTrigger render={<Button variant="outline" />}>
+    Open settings
+  </PopoverTrigger>
+  <PopoverContent align="end">
+    <PopoverTitle>Display settings</PopoverTitle>
+    <PopoverDescription>Choose the list density.</PopoverDescription>
+  </PopoverContent>
+</Popover>
+```
+
+The local API continues to forward Base UI Popup and Positioner props. Pass `open` and `onOpenChange` to `Popover` when controlled state is required.
+
+## Continuous tail {#anchored-surface}
+
+The local `showArrow` is more than a triangular SVG. It renders `PopoverContent` through `AnchoredSurface`, producing one rounded surface with a continuous curved tail:
+
+```tsx
+<PopoverContent
+  side="bottom"
+  showArrow={{ cornerRadius: "2xl", tailSize: "sm" }}
+  className="w-80 p-0"
+  viewportClassName="max-h-72 p-4"
+>
+  {content}
+</PopoverContent>
+```
+
+The outer surface remains `overflow: visible` so the tail is not clipped. Scrolling happens inside `data-slot="popover-viewport"`. Use `viewportClassName` when constraining content height or applying content padding.
+
+`AnchoredSurface` can also render on its own, but it is visual only: it does not own anchor measurement, collision detection, focus, or a portal.
+
+## Custom positioning {#positioning}
+
+`PopoverContent` additionally exposes `anchor`, `positionMethod`, `arrowPadding`, `alignOffset`, and `sideOffset`. Pass virtual or custom anchors through the shared component instead of rebuilding the Base UI primitives.
+
+For control outside React, create a handle with `createPopoverHandle<Payload>()` and connect it to the Root using Base UI's handle pattern.
+
+## Choose an overlay {#choosing-an-overlay}
+
+- Block background interaction with `Dialog` or `AlertDialog`.
+- Use `Sheet` for a task surface entering from a screen edge and `Drawer` for a touch-oriented mobile panel.
+- Use `Popover` for interactive content attached to a trigger.
+- Use `HoverCard` for a preview revealed by hover or focus.
+- Use `Tooltip` for short, non-interactive descriptions.
+
+Compare basic usage with the [shadcn Popover documentation](https://ui.shadcn.com/docs/components/base/popover), but keep the Base UI `render` composition syntax.