# Popover

<!-- begin:auto-docs -->
_(no submodules)_
<!-- end:auto-docs --> - popover.variants — `popoverContentVariants` is the……
- [popover.variants](./popover.variants.md) — `popoverContentVariants` is the cva configuration powering the `<PopoverContent>` floating panel. It is split from `pop…
- popover.variants — `popoverContentVariants` is the……

- [popover.variants](./popover.variants.md) — `popoverContentVariants` is the cva configuration powering the `<PopoverContent>` floating panel. It is split from `pop…

- popover.variants — `popoverContentVariants` is the……

- [popover.variants](./popover.variants.md) — `popoverContentVariants` is the cva configuration powering the `<PopoverContent>` floating panel. It is split from `pop…

- popover.variants — `popoverContentVariants` is the…

- [popover.variants](./popover.variants.md) — `popoverContentVariants` is the cva configuration powering the `<PopoverContent>` floating panel. It is split from `pop…
- [popover.variants](./popover.variants.md) — `popoverContentVariants` is the cva configuration powering the `<PopoverContent>` floating panel. It is split from `pop…

## Purpose

`<Popover>` and its sub-components (`<PopoverTrigger>`, `<PopoverAnchor>`, `<PopoverPortal>`, `<PopoverContent>`, `<PopoverArrow>`, `<PopoverClose>`) are the chassis floating-panel primitives built on `@radix-ui/react-popover`. Use this for non-modal ephemeral content — info bubbles, compact pickers, link previews — where focus does NOT need to be trapped.

Distinct from `<Dialog>` and `<AlertDialog>`: a popover is non-modal so focus is not trapped, clicking outside dismisses it, and Escape dismisses it. There is no required title (popovers narrate their accessible name via their content). Radix handles the floating-UI math (avoid-collisions, sticky positioning, side/align resolution); the chassis adds the cva visual recipe.

## Features

- Side / align positional API (`side`: top/right/bottom/left; `align`: start/center/end).
- `sideOffset` / `alignOffset` numeric offsets pass through to Radix.
- Self-portals via `<PopoverPortal>` so consumers do not need to compose the portal manually.
- Click-outside dismissal.
- Escape closes.
- Optional `<PopoverArrow>` decoration pointing back at the trigger.
- Optional `<PopoverAnchor>` lets the visual trigger differ from the popover anchor (e.g. anchor to a parent container).
- Theme-driven cva via `useThemedVariants("PopoverContent")`.
- All sub-components forward refs.
- `motion-reduce:animate-none` collapses the open/close animations under `prefers-reduced-motion: reduce`.

## Usage: Basic Example

```tsx
import {
    Popover,
    PopoverContent,
    PopoverTrigger,
} from "@suaveplan/react-ui";

export function HelpBubble() {
    return (
        <Popover>
            <PopoverTrigger>Help</PopoverTrigger>
            <PopoverContent>
                Detailed help text for the focused control.
            </PopoverContent>
        </Popover>
    );
}
```

## Usage: Advanced Example

```tsx
import {
    Popover,
    PopoverArrow,
    PopoverAnchor,
    PopoverClose,
    PopoverContent,
    PopoverTrigger,
} from "@suaveplan/react-ui";
import { useState } from "react";

export function ColorPicker() {
    const [color, setColor] = useState("#3b82f6");
    return (
        <Popover>
            <PopoverTrigger
                aria-label="Pick a colour"
                style={{ background: color, width: 24, height: 24 }}
            />
            <PopoverContent side="bottom" align="start" sideOffset={8}>
                <PopoverArrow />
                <input
                    type="color"
                    value={color}
                    onChange={(e) => setColor(e.target.value)}
                />
                <PopoverClose>Done</PopoverClose>
            </PopoverContent>
        </Popover>
    );
}
```

## API Reference

### `<Popover>`

Wraps the Radix Popover Root. Same `open` / `defaultOpen` / `onOpenChange` lifecycle props as the other overlays.

### `<PopoverTrigger>`

The visual trigger — a `<button>` by default; `asChild` polymorphic.

### `<PopoverContent>`

| Prop | Type | Default | Description |
|---|---|---|---|
| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | Preferred side of the trigger. |
| `align` | `"start" \| "center" \| "end"` | `"center"` | Alignment along the perpendicular axis. |
| `sideOffset` | `number` | `4` | Numeric offset along the side axis. |
| `alignOffset` | `number` | `0` | Numeric offset along the align axis. |
| `avoidCollisions` | `boolean` | `true` | Allow Radix to reposition to avoid viewport edges. |
| `collisionPadding` | `number \| Padding` | `0` | Padding from viewport edges. |

### `<PopoverAnchor>`

Optional — overrides the positioning anchor. When omitted, the popover anchors to the `<PopoverTrigger>`.

### `<PopoverArrow>`, `<PopoverClose>`, `<PopoverPortal>`

Direct re-exports of the Radix sub-components.

## Implementation Notes

- The chassis NEVER assigns a numeric `z-index` — Radix portals handle stacking.
- `<PopoverContent>` self-portals via `<PopoverPortal>` so consumers do not need to compose the portal manually.
- `align="center"` and `sideOffset={4}` are chassis defaults (matching shadcn upstream) — overridable per call.
- `data-side="<side>"` is used by the cva animation classes — Radix sets it once positioning is resolved (which may differ from the requested `side` if `avoidCollisions` kicked in).
- For modal confirmation surfaces use `<Dialog>` or `<AlertDialog>` — Popover is intentionally non-modal so focus is NOT trapped.