feat(headless): add Popover primitive

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"

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';
+
+<Popover>
+  <Popover.Trigger>Settings</Popover.Trigger>
+  <Popover.Positioner>
+    <Popover.Popup>
+      <Popover.Title>Preferences</Popover.Title>
+      <Popover.Description>Adjust your settings below.</Popover.Description>
+      {/* Interactive content here */}
+      <Popover.Close>Done</Popover.Close>
+    </Popover.Popup>
+  </Popover.Positioner>
+</Popover>;
+```
+
+### Controlled
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Popover
+  open={open}
+  onOpenChange={setOpen}
+>
+  {/* ... */}
+</Popover>;
+```
+
+### Modal Mode
+
+```tsx
+<Popover modal>{/* Focus is trapped within the popover */}</Popover>
+```
+
+## Parts
+
+| Part                  | Default Element | Description                              |
+| --------------------- | --------------- | ---------------------------------------- |
+| `Popover`             | —               | Root context provider                    |
+| `Popover.Trigger`     | `<button>`      | Toggles the popover on click             |
+| `Popover.Portal`      | —               | Portals children (accepts `root` prop)   |
+| `Popover.Positioner`  | `<div>`         | Floating positioned container            |
+| `Popover.Popup`       | `<div>`         | Visual content wrapper                   |
+| `Popover.Arrow`       | `<svg>`         | Optional floating arrow                  |
+| `Popover.Title`       | `<h2>`          | Heading, wired to `aria-labelledby`      |
+| `Popover.Description` | `<p>`           | Description, wired to `aria-describedby` |
+| `Popover.Close`       | `<button>`      | Closes the popover on click              |
+
+## Props
+
+### `Popover` (root)
+
+| Prop           | Type                      | Default    | Description                        |
+| -------------- | ------------------------- | ---------- | ---------------------------------- |
+| `open`         | `boolean`                 | —          | Controlled open state              |
+| `defaultOpen`  | `boolean`                 | `false`    | Initial open state (uncontrolled)  |
+| `onOpenChange` | `(open: boolean) => void` | —          | Called when open state changes     |
+| `placement`    | `Placement`               | `"bottom"` | Floating UI placement              |
+| `sideOffset`   | `number`                  | `4`        | Gap between trigger and popup (px) |
+| `modal`        | `boolean`                 | `false`    | Traps focus within the popover     |
+
+### `Popover.Trigger`, `Popover.Positioner`, `Popover.Popup`, `Popover.Title`, `Popover.Description`, `Popover.Close`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Popover.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard
+
+| Key      | Action                                                               |
+| -------- | -------------------------------------------------------------------- |
+| `Escape` | Closes the popover                                                   |
+| `Tab`    | Cycles focus within popover (modal mode) or moves freely (non-modal) |
+
+## Data Attributes
+
+| Attribute                         | Applies To        | Description                              |
+| --------------------------------- | ----------------- | ---------------------------------------- |
+| `data-cl-slot`                    | All parts         | Part identifier (e.g. `"popover-popup"`) |
+| `data-cl-open` / `data-cl-closed` | Trigger           | Open state                               |
+| `data-cl-side`                    | Positioner, Arrow | Resolved placement side                  |
+
+## Positioning
+
+Middleware stack: `offset` -> `flip` -> `shift` -> `arrow` -> CSS vars. The popup auto-repositions on scroll and resize via `autoUpdate`. Cross-axis flipping is enabled only when using an aligned placement (e.g. `"bottom-start"`).
+
+## Important Notes
+
+- **Title and Description are optional but recommended.** They wire `aria-labelledby` and `aria-describedby` to the positioner. If omitted, those attributes are simply absent.
+- **Non-modal by default.** Unlike Dialog, the page remains interactive behind the popover. Set `modal={true}` for a stricter focus trap.
+- **Nested popovers are supported.** The `FloatingTree` pattern handles nesting automatically.
+
+## ARIA
+
+- Positioner: `role="dialog"`, `aria-labelledby` (from Title), `aria-describedby` (from Description)
+- Trigger: `aria-expanded`, `aria-haspopup="dialog"`, `aria-controls`

packages/headless/src/primitives/popover/index.ts

@@ -0,0 +1,12 @@
+export type {
+  PopoverArrowProps,
+  PopoverCloseProps,
+  PopoverDescriptionProps,
+  PopoverPopupProps,
+  PopoverPortalProps,
+  PopoverPositionerProps,
+  PopoverProps,
+  PopoverTitleProps,
+  PopoverTriggerProps,
+} from './popover';
+export { Popover } from './popover';

packages/headless/src/primitives/popover/popover.test.tsx

@@ -0,0 +1,259 @@
+import { cleanup, render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { axe } from '../../test-utils/axe';
+import { Popover } from './popover';
+
+afterEach(() => cleanup());
+
+function renderPopover(props: Partial<React.ComponentProps<typeof Popover>> = {}) {
+  return render(
+    <Popover {...props}>
+      <Popover.Trigger>Open popover</Popover.Trigger>
+      <Popover.Positioner>
+        <Popover.Popup>
+          <Popover.Title>Popover Title</Popover.Title>
+          <Popover.Description>Some description</Popover.Description>
+          <p>Popover content</p>
+          <Popover.Close>Close</Popover.Close>
+        </Popover.Popup>
+      </Popover.Positioner>
+    </Popover>,
+  );
+}
+
+describe('Popover', () => {
+  describe('slot attributes', () => {
+    it('renders trigger with data-cl-slot', () => {
+      renderPopover();
+      const trigger = screen.getByRole('button', { name: 'Open popover' });
+      expect(trigger).toHaveAttribute('data-cl-slot', 'popover-trigger');
+    });
+
+    it('renders all parts with correct slot attributes when open', () => {
+      renderPopover({ defaultOpen: true });
+
+      expect(document.querySelector('[data-cl-slot="popover-positioner"]')).toBeInTheDocument();
+      expect(document.querySelector('[data-cl-slot="popover-popup"]')).toBeInTheDocument();
+      expect(document.querySelector('[data-cl-slot="popover-title"]')).toBeInTheDocument();
+      expect(document.querySelector('[data-cl-slot="popover-description"]')).toBeInTheDocument();
+      expect(document.querySelector('[data-cl-slot="popover-close"]')).toBeInTheDocument();
+    });
+  });
+
+  describe('open/close', () => {
+    it('opens on trigger click', async () => {
+      const user = userEvent.setup();
+      renderPopover();
+
+      const trigger = screen.getByRole('button', { name: 'Open popover' });
+      await user.click(trigger);
+
+      expect(trigger).toHaveAttribute('data-cl-open', '');
+      expect(document.querySelector('[data-cl-slot="popover-popup"]')).toBeInTheDocument();
+    });
+
+    it('closes on trigger click when open', async () => {
+      const user = userEvent.setup();
+      renderPopover();
+
+      const trigger = screen.getByRole('button', { name: 'Open popover' });
+      await user.click(trigger);
+      await user.click(trigger);
+
+      expect(trigger).toHaveAttribute('data-cl-closed', '');
+    });
+
+    it('closes on Escape', async () => {
+      const user = userEvent.setup();
+      renderPopover({ defaultOpen: true });
+
+      await user.keyboard('{Escape}');
+
+      const trigger = screen.getByRole('button', { name: 'Open popover' });
+      expect(trigger).toHaveAttribute('data-cl-closed', '');
+    });
+
+    it('closes via Close button', async () => {
+      const user = userEvent.setup();
+      renderPopover({ defaultOpen: true });
+
+      const closeBtn = screen.getByRole('button', { name: 'Close' });
+      await user.click(closeBtn);
+
+      const trigger = screen.getByRole('button', { name: 'Open popover' });
+      expect(trigger).toHaveAttribute('data-cl-closed', '');
+    });
+
+    it('calls onOpenChange when toggled', async () => {
+      const onOpenChange = vi.fn();
+      const user = userEvent.setup();
+      renderPopover({ onOpenChange });
+
+      const trigger = screen.getByRole('button', { name: 'Open popover' });
+      await user.click(trigger);
+
+      expect(onOpenChange).toHaveBeenCalledWith(true);
+    });
+
+    it('closes on outside click', async () => {
+      const user = userEvent.setup();
+      renderPopover({ defaultOpen: true });
+
+      expect(document.querySelector('[data-cl-slot="popover-popup"]')).toBeInTheDocument();
+
+      await user.click(document.body);
+
+      expect(document.querySelector('[data-cl-slot="popover-popup"]')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('controlled open', () => {
+    it('respects controlled open prop', () => {
+      renderPopover({ open: true });
+
+      expect(document.querySelector('[data-cl-slot="popover-positioner"]')).toBeInTheDocument();
+    });
+
+    it('does not open when controlled open is false', async () => {
+      const user = userEvent.setup();
+      renderPopover({ open: false });
+
+      await user.click(screen.getByRole('button', { name: 'Open popover' }));
+
+      expect(document.querySelector('[data-cl-slot="popover-positioner"]')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('ARIA attributes', () => {
+    it('positioner has aria-labelledby linked to title', () => {
+      renderPopover({ defaultOpen: true });
+
+      const title = document.querySelector('[data-cl-slot="popover-title"]');
+      const positioner = document.querySelector('[data-cl-slot="popover-positioner"]');
+
+      expect(title).toHaveAttribute('id');
+      expect(positioner).toHaveAttribute('aria-labelledby', title?.getAttribute('id'));
+    });
+
+    it('positioner has aria-describedby linked to description', () => {
+      renderPopover({ defaultOpen: true });
+
+      const desc = document.querySelector('[data-cl-slot="popover-description"]');
+      const positioner = document.querySelector('[data-cl-slot="popover-positioner"]');
+
+      expect(desc).toHaveAttribute('id');
+      expect(positioner).toHaveAttribute('aria-describedby', desc?.getAttribute('id'));
+    });
+
+    it('trigger has role=button', () => {
+      renderPopover();
+      expect(screen.getByRole('button', { name: 'Open popover' })).toBeInTheDocument();
+    });
+  });
+
+  describe('animation lifecycle', () => {
+    it('positioner is not rendered when closed', () => {
+      renderPopover();
+      expect(document.querySelector('[data-cl-slot="popover-positioner"]')).not.toBeInTheDocument();
+    });
+
+    it('applies data-cl-open on popup when open', async () => {
+      const user = userEvent.setup();
+      renderPopover();
+
+      await user.click(screen.getByRole('button', { name: 'Open popover' }));
+
+      const popup = document.querySelector('[data-cl-slot="popover-popup"]');
+      expect(popup).toHaveAttribute('data-cl-open', '');
+    });
+
+    it('positioner has data-cl-side', async () => {
+      const user = userEvent.setup();
+      renderPopover();
+
+      await user.click(screen.getByRole('button', { name: 'Open popover' }));
+
+      const positioner = document.querySelector('[data-cl-slot="popover-positioner"]');
+      expect(positioner).toHaveAttribute('data-cl-side');
+    });
+  });
+
+  describe('content rendering', () => {
+    it('renders children content when open', async () => {
+      const user = userEvent.setup();
+      renderPopover();
+
+      await user.click(screen.getByRole('button', { name: 'Open popover' }));
+
+      expect(screen.getByText('Popover content')).toBeInTheDocument();
+      expect(screen.getByText('Popover Title')).toBeInTheDocument();
+      expect(screen.getByText('Some description')).toBeInTheDocument();
+    });
+  });
+
+  describe('placement', () => {
+    it('accepts custom placement', () => {
+      renderPopover({ defaultOpen: true, placement: 'top-start' });
+
+      const positioner = document.querySelector('[data-cl-slot="popover-positioner"]');
+      expect(positioner).toHaveAttribute('data-cl-side', 'top');
+    });
+
+    it('defaults to bottom placement', () => {
+      renderPopover({ defaultOpen: true });
+
+      const positioner = document.querySelector('[data-cl-slot="popover-positioner"]');
+      expect(positioner).toHaveAttribute('data-cl-side', 'bottom');
+    });
+  });
+
+  describe('focus management', () => {
+    it('moves focus into popover on open', async () => {
+      const user = userEvent.setup();
+      renderPopover();
+
+      await user.click(screen.getByRole('button', { name: 'Open popover' }));
+      // FloatingFocusManager schedules focus via requestAnimationFrame
+      await new Promise(r => requestAnimationFrame(r));
+
+      const positioner = document.querySelector('[data-cl-slot="popover-positioner"]');
+      expect(positioner?.contains(document.activeElement)).toBe(true);
+    });
+
+    it('returns focus to trigger on close via Escape', async () => {
+      const user = userEvent.setup();
+      renderPopover();
+
+      const trigger = screen.getByRole('button', { name: 'Open popover' });
+      await user.click(trigger);
+      await user.keyboard('{Escape}');
+
+      expect(document.activeElement).toBe(trigger);
+    });
+
+    it('returns focus to trigger on close via Close button', async () => {
+      const user = userEvent.setup();
+      renderPopover();
+
+      const trigger = screen.getByRole('button', { name: 'Open popover' });
+      await user.click(trigger);
+
+      await user.click(screen.getByRole('button', { name: 'Close' }));
+
+      expect(document.activeElement).toBe(trigger);
+    });
+  });
+
+  describe('accessibility (axe)', () => {
+    it('has no violations when closed', async () => {
+      const { container } = renderPopover();
+      expect(await axe(container)).toHaveNoViolations();
+    });
+
+    it('has no violations when open', async () => {
+      renderPopover({ defaultOpen: true });
+      expect(await axe(document.body, { rules: { region: { enabled: false } } })).toHaveNoViolations();
+    });
+  });
+});