---

## Popover
Floating panel anchored to a trigger element. Uses the native Popover API
for top-layer rendering, light dismiss, and Escape handling. Floating UI provides
precise positioning with automatic flip, shift, and optional width syncing.

**Import:** `import { Popover } from '@urbicon-ui/blocks';`

### Examples
```svelte
<Popover placement="bottom-start">
  {#snippet trigger()}
    <Button>Open</Button>
  {/snippet}
  {#snippet children()}
    <div class="p-3">Popover content</div>
  {/snippet}
</Popover>
```

```svelte
<Popover placement="top" arrow bind:open={showInfo}>
  {#snippet trigger()}
    <Button variant="ghost" size="sm">More info</Button>
  {/snippet}
  {#snippet children()}
    <div class="max-w-xs p-4">
      <h4 class="font-semibold">Details</h4>
      <p class="text-text-secondary text-sm">Additional context shown in a floating panel.</p>
    </div>
  {/snippet}
</Popover>
```

### Variants
- size: lg, md, sm (default: md)

### Api
| Prop | Type | Required | Default | Description |
| --- | --- | :---: | --- | --- |
| children | `Snippet` | yes |  | Popover body rendered inside the floating panel. |
| ...HTMLAttributes<HTMLDivElement> | `HTMLAttributes` | no |  | HTML attributes (excluding: 'children') |
| ...PopoverVariants | `VariantProps` | no |  | Styling variants from PopoverVariants |
| autoTrigger | `boolean` | no |  | When true (default), the trigger wrapper handles click and keyboard to toggle the popover. Set to `false` to manage `open` yourself. |
| class | `string` | no |  | Extra classes merged onto the floating panel element. |
| closeOnClickOutside | `boolean` | no |  | Whether the popover closes on outside click / pointer interaction. Default `true`. Set to `false` to pin the popover open until the consumer explicitly toggles `open`. |
| closeOnEscape | `boolean` | no |  | Whether the popover closes on Escape key. Default `true`. Set to `false` for cases where Escape should be intercepted by an inner widget (e.g. an editable cell that wants to revert on Escape). |
| offsetDistance | `number` | no |  | Gap in px between the trigger edge and the popover. |
| onClickOutside | `() => void` | no |  | Fires after an outside click closes the popover. Use for analytics or to clear ephemeral state on dismiss. Does NOT control whether the popover closes — that is governed by `closeOnClickOutside`. |
| onEscape | `() => void` | no |  | Fires after Escape closes the popover. Use for analytics or to clear ephemeral state on dismiss. Does NOT control whether the popover closes — that is governed by `closeOnEscape`. |
| onOpenChange | `(open: boolean) => void` | no |  | Fires when the popover opens or closes from user interaction (click, escape, click-outside). Receives the new open state. |
| open | `boolean` | no |  | Controlled open state. Supports `bind:open`. |
| placement | `Placement` | no |  | Where the popover appears relative to the trigger. All Floating UI `Placement` values are supported. |
| preset | `string` | no |  | Apply a named preset registered via `<BlocksProvider presets={{ Popover: {...} }}>`. Prefer this over `class` overrides when the requested look falls outside the semantic intent palette — presets keep hover/active/dark-mode logic coherent and make the custom look reusable across the project. |
| shiftPadding | `number` | no |  | Minimum px padding from viewport edges when the popover shifts to stay visible. |
| slotClasses | `Partial<Record<'base', string>>` | no |  | Per-slot class overrides. Available slots: `base` (the floating panel). |
| syncMinWidth | `boolean` | no |  | Match the popover's *minimum* width to the trigger width while still letting content grow the panel beyond it. Useful for menu-style overlays where items longer than the trigger should not get truncated. Ignored when `syncWidth` is true (hard width wins). |
| syncWidth | `boolean` | no |  | Match the popover width to the trigger width. Useful for select/autocomplete patterns where the floating panel should align with the input. |
| trigger | `Snippet` | no |  | Trigger element that anchors and toggles the popover. Receives click/keyboard handlers when `autoTrigger` is true. |
| triggerElement | `HTMLElement` | no |  | External trigger element ref. Use instead of the `trigger` snippet when the trigger lives outside the Popover tree. Supports `bind:triggerElement`. |
| unstyled | `boolean` | no |  | Strip all default tv() classes. Combine with `class` or `slotClasses` for full custom styling. |
| usePortal | `boolean` | no | true | Render the floating panel into the browser's top layer via the native `popover` attribute, so it cannot be clipped by `overflow: auto` ancestors. Set to `false` when the popover is itself embedded inside another floating surface (Dialog, Drawer, another Popover) — nested top-layer rendering stacks unpredictably across browsers and stealing focus from the parent surface is usually unwanted. In-flow mode positions the panel absolutely relative to the trigger's offset parent. |
| size | `'lg' | 'md' | 'sm'` | no | md | Controls the dimensions, padding, and text size of the Popover. Affects the component's physical footprint. Available options: lg, md, sm. |

Inherited from:
- PopoverVariants (external)
- Omit<HTMLAttributes<HTMLDivElement>, 'children'> (omit-pattern)

### Slots (slotClasses keys)
`base`