# Popover

## Overview

A floating panel anchored to a trigger element that presents additional information or controls without navigating away from the current context. Unlike `Tooltip`, Popover content can be interactive — forms, date pickers, settings panels, filter controls.

---

## When to Use

- Inline date pickers (Calendar inside Popover)
- Compact filter panels triggered by a button
- Contextual settings or configuration controls
- Preview panels for complex data that don't need a full Sheet

## When NOT to Use

- Simple text descriptions — use `<Tooltip>` instead.
- Long forms or large content areas — use `<Sheet>` or `<Dialog>` instead.
- Persistent content visible at all times — place inline in the page.

---

## Anatomy

```
<Popover>
  <PopoverTrigger asChild>
    <Button />
  </PopoverTrigger>
  <PopoverContent>
    {/* Interactive content */}
  </PopoverContent>
</Popover>
```

---

## Props

### Popover

| Prop           | Type                      | Description           |
| -------------- | ------------------------- | --------------------- |
| `open`         | `boolean`                 | Controlled open state |
| `onOpenChange` | `(open: boolean) => void` | State handler         |

### PopoverContent

| Prop         | Type                                     | Default    | Description               |
| ------------ | ---------------------------------------- | ---------- | ------------------------- |
| `align`      | `'start' \| 'center' \| 'end'`           | `'center'` | Horizontal alignment      |
| `side`       | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` | Positioning side          |
| `sideOffset` | `number`                                 | `4`        | Distance from trigger     |
| `className`  | `string`                                 | —          | Width and style overrides |

---

## Examples

### Date Picker Popover

```tsx
import { Popover, PopoverContent, PopoverTrigger, Button, Calendar } from 'xertica-ui/ui';
import { CalendarIcon } from 'lucide-react';
import { useState } from 'react';

const [date, setDate] = useState<Date>();

<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline" className="gap-2">
      <CalendarIcon className="size-4" />
      {date ? format(date, 'PPP') : 'Pick a date'}
    </Button>
  </PopoverTrigger>
  <PopoverContent className="w-auto p-0" align="start">
    <Calendar mode="single" selected={date} onSelect={setDate} initialFocus />
  </PopoverContent>
</Popover>;
```

### Filter Panel

```tsx
<Popover>
  <PopoverTrigger asChild>
    <Button variant="outline" className="gap-2">
      <Filter className="size-4" /> Filters
    </Button>
  </PopoverTrigger>
  <PopoverContent className="w-64 p-4">
    <div className="space-y-4">
      <h4 className="font-medium">Filter by Status</h4>
      {/* Filter controls */}
    </div>
  </PopoverContent>
</Popover>
```

---

## AI Rules

- `<PopoverTrigger asChild>` is **required** when the trigger is a `<Button>`.
- For date pickers, always set `className="w-auto p-0"` on `<PopoverContent>` to let the `<Calendar>` define its own size.
- Popover content is lazy-rendered — don't rely on it being in the DOM when the popover is closed.

---

## Related Components

- [`Tooltip`](./tooltip.md) — For non-interactive hover hints
- [`HoverCard`](./hover-card.md) — For hover-triggered rich previews
- [`Calendar`](./calendar.md) — The most common Popover content
- [`Sheet`](./sheet.md) — For larger panel content