diff --git a/packages/headless/package.json b/packages/headless/package.json index 3c3e24d0d99..97ecfbd4c03 100644 --- a/packages/headless/package.json +++ b/packages/headless/package.json @@ -16,6 +16,10 @@ "import": "./dist/primitives/tooltip/index.js", "types": "./dist/primitives/tooltip/index.d.ts" }, + "./popover": { + "import": "./dist/primitives/popover/index.js", + "types": "./dist/primitives/popover/index.d.ts" + }, "./dialog": { "import": "./dist/primitives/dialog/index.js", "types": "./dist/primitives/dialog/index.d.ts" diff --git a/packages/headless/src/primitives/popover/README.md b/packages/headless/src/primitives/popover/README.md new file mode 100644 index 00000000000..c320cdd1a0b --- /dev/null +++ b/packages/headless/src/primitives/popover/README.md @@ -0,0 +1,111 @@ +# Popover + +A floating panel anchored to a trigger element. Supports focus management, ARIA labeling, and enter/exit animations. + +## When to Use + +- Rich content panels, filter dropdowns, or any non-modal floating content anchored to a trigger. +- When content includes interactive elements (inputs, buttons) — unlike Tooltip which is display-only. +- Prefer Popover over Dialog when the content should be anchored to a specific element and the page should remain interactive by default. + +## Usage + +```tsx +import { Popover } from '@/primitives/popover'; + + + Settings + + + Preferences + Adjust your settings below. + {/* Interactive content here */} + Done + + +; +``` + +### Controlled + +```tsx +const [open, setOpen] = useState(false); + + + {/* ... */} +; +``` + +### Modal Mode + +```tsx +{/* Focus is trapped within the popover */} +``` + +## Parts + +| Part | Default Element | Description | +| --------------------- | --------------- | ---------------------------------------- | +| `Popover` | — | Root context provider | +| `Popover.Trigger` | `