# Popover

> Positioned floating panel for menus, forms, and custom UI. `role="dialog"` with focus management.

- Package: `@sisyphos-ui/popover`
- Docs: https://sisyphosui.com/docs/components/popover
- npm: https://www.npmjs.com/package/@sisyphos-ui/popover

## Installation

```bash
pnpm add @sisyphos-ui/popover @sisyphos-ui/core
```

Or use the umbrella package:

```bash
pnpm add @sisyphos-ui/ui
```

## Import

```tsx
import "@sisyphos-ui/popover/styles.css";
import { Popover } from "@sisyphos-ui/popover";
```

## Examples

### Default

Interactive floating panel — focusable, outside-click dismissable.

```tsx
import { useState } from "react";
import { Button, Popover } from "@sisyphos-ui/ui";

export function Example() {
  const [open, setOpen] = useState(false);

  return (
    <Popover
      open={open}
      onOpenChange={setOpen}
      content={
        <div className="w-64 p-4">
          <h4 className="text-sm font-semibold">Workspace settings</h4>
          <p className="mt-1 text-xs text-neutral-500">
            Update your workspace name and default timezone.
          </p>
          <div className="mt-3 flex justify-end gap-2">
            <Button size="sm" variant="text" onClick={() => setOpen(false)}>Cancel</Button>
            <Button size="sm" onClick={() => setOpen(false)}>Save</Button>
          </div>
        </div>
      }
    >
      <Button variant="outlined">Open popover</Button>
    </Popover>
  );
}
```

### Hover trigger

`trigger="hover"` shows the popover on hover/focus like a richer tooltip.

```tsx
import { Button, Popover } from "@sisyphos-ui/ui";

export function Example() {
  return (
    <Popover
      trigger="hover"
      openDelay={150}
      closeDelay={200}
      content={
        <div>
          <div>@ada.lovelace</div>
          <div>Admin · joined 3 years ago · 142 projects</div>
        </div>
      }
    >
      <Button variant="text">@ada.lovelace</Button>
    </Popover>
  );
}
```

### Manual trigger

`trigger="manual"` hands full open/close control to the parent — ideal for form flows and shortcuts.

```tsx
import { useState } from "react";
import { Button, Popover } from "@sisyphos-ui/ui";

export function Example() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <Popover
        trigger="manual"
        open={open}
        onOpenChange={setOpen}
        content={<div>Triggered from outside.</div>}
      >
        <span>Anchor element</span>
      </Popover>
      <Button size="sm" onClick={() => setOpen(v => !v)}>
        {open ? "Close" : "Open"} from outside
      </Button>
    </>
  );
}
```

### Placements

Auto-flipping placement reroutes the popover when it doesn't fit.

```tsx
import { useState } from "react";
import { Button, Popover } from "@sisyphos-ui/ui";

export function Example() {
  const [placement, setPlacement] = useState<"top" | "bottom" | "left" | "right">("top");

  return (
    <>
      {(["top", "bottom", "left", "right"] as const).map((p) => (
        <Button key={p} size="sm" onClick={() => setPlacement(p)}>{p}</Button>
      ))}
      <Popover key={placement} placement={placement} content={<div>Placement = {placement}</div>}>
        <Button variant="outlined">Anchor</Button>
      </Popover>
    </>
  );
}
```