# swc-popover

An anchored popover surface that renders an internal top-layer element.

```js
import '@adobe/spectrum-wc/components/popover/index.js';
// <swc-popover></swc-popover>
```

## Attributes

| Name               | Type                       | Default    | Description                                                                                                                                                                                             |
| ------------------ | -------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `open`             | `boolean`                  | `false`    | Whether the popover is open.                                                                                                                                                                            |
| `modal`            | `boolean`                  | `false`    | Opt in to blocking modal behavior (`<dialog>.showModal()`): focus trap, background inert, native `role="dialog"`. When unset, the popover uses `popover="auto"` light-dismiss behavior.                 |
| `accessible-label` | `string`                   | `''`       | Accessible name for the popover's dialog surface, forwarded as `aria-label` to the internal element. Required in both modes (the surface is a dialog); the component dev-warns when opened without one. |
| `placement`        | `Placement`                | `'bottom'` | The placement of the popover relative to its trigger.                                                                                                                                                   |
| `size`             | `PopoverSize \| undefined` | -          | Optional fixed size. When set, the popover uses a fixed inline size (`s` → 336px, `m` → 416px, `l` → 576px); when unset, it fits its contents.                                                          |
| `hide-arrow`       | `boolean`                  | `false`    | Hide the popover's arrow (tip). The arrow is shown by default.                                                                                                                                          |
| `offset`           | `number`                   | `8`        | Main-axis offset in pixels from the trigger.                                                                                                                                                            |
| `cross-offset`     | `number`                   | `0`        | Cross-axis offset in pixels from the trigger.                                                                                                                                                           |
| `should-flip`      | `boolean`                  | `true`     | Allow the popover to flip to the opposite side when constrained. When `false`, the popover stays in the requested placement.                                                                            |
| `for`              | `string \| undefined`      | -          | ID of the trigger element in the same document tree root.                                                                                                                                               |
| `manual`           | `boolean`                  | `false`    | Suppress the automatic click-to-toggle wiring on the resolved trigger. When set, control visibility through the `open` property instead. ARIA relationship wiring still applies.                        |

## Slots

| Name        | Description      |
| ----------- | ---------------- |
| `(default)` | Popover content. |

## Events

| Name              | Description                                                                                                       |
| ----------------- | ----------------------------------------------------------------------------------------------------------------- |
| `swc-open`        | Dispatched when the popover begins opening.                                                                       |
| `swc-after-open`  | Dispatched after the open transition completes.                                                                   |
| `swc-close`       | Dispatched when the popover begins closing. `detail.source` reports `'escape'`, `'outside'`, or `'programmatic'`. |
| `swc-after-close` | Dispatched after the close transition completes.                                                                  |

## CSS Custom Properties

| Name                             | Description                                                                                  |
| -------------------------------- | -------------------------------------------------------------------------------------------- |
| `--swc-popover-content-padding`  | Padding around the slotted content. Defaults to the `popover-padding` token.                 |
| `--swc-popover-background-color` | Background color of the surface and arrow. Defaults to the `background-layer-2-color` token. |
| `--swc-popover-border-color`     | Border color of the surface and arrow. Defaults to the `popover-border-color` token.         |
| `--swc-popover-corner-radius`    | Corner radius of the surface. Defaults to the `corner-radius-700` token.                     |