@reliability-design/web 1.4.9 → 1.4.10

package/dist/components/rel-popover/README.md

@@ -1,203 +1,220 @@
-# rel-popover
-
-A click-to-open floating panel anchored to a trigger, implementing the Figma "Popover" component (including its opt-in chevron). The folder registers two elements: `<rel-popover>` is the controller — its first child is the trigger, its `content` slot is the panel — and `<rel-popover-content>` is the optional styled surface (neutral background, border, radius, shadow, S/M/L padding) you drop into that slot. The panel is promoted to the browser top layer and positioned in viewport coordinates, so it renders correctly even inside a centred `<rel-modal>`. Use it for rich, interactive content that needs an explicit click — small forms, filters, menus, detail cards. For a short hover label use `<rel-tooltip>`; for a task that must be completed before continuing use `<rel-modal>`.
-
-## Usage
-
-```html
-<!-- Basic: first child = trigger, slot="content" = panel -->
-<rel-popover>
-  <rel-button>Open</rel-button>
-  <rel-popover-content aria-label="About popovers">
-    <h3>Popover title</h3>
-    <p>Any HTML can go here.</p>
-  </rel-popover-content>
-</rel-popover>
-
-<!-- Panel padding (Figma Size S / M / L = 12 / 16 / 20px) -->
-<rel-popover>
-  <rel-button variant="secondary">Compact</rel-button>
-  <rel-popover-content size="small" aria-label="Compact panel"><p>12px padding</p></rel-popover-content>
-</rel-popover>
-<rel-popover>
-  <rel-button variant="secondary">Roomy</rel-button>
-  <rel-popover-content size="large" aria-label="Roomy panel"><p>20px padding</p></rel-popover-content>
-</rel-popover>
-
-<!-- Positioning: side, alignment and pixel offsets -->
-<rel-popover side="top" align="start">
-  <rel-button>Top / start</rel-button>
-  <rel-popover-content aria-label="Top start"><p>Above the trigger, left edges aligned.</p></rel-popover-content>
-</rel-popover>
-<rel-popover side="right" sideoffset="16" alignoffset="8">
-  <rel-button>Right, 16px away</rel-button>
-  <rel-popover-content aria-label="Right offset"><p>16px gap, shifted 8px down.</p></rel-popover-content>
-</rel-popover>
-
-<!-- Chevron pointing at the trigger -->
-<rel-popover side="bottom" arrow>
-  <rel-button>With arrow</rel-button>
-  <rel-popover-content aria-label="Arrow demo"><p>The chevron follows the trigger centre.</p></rel-popover-content>
-</rel-popover>
-
-<!-- Any element can be the trigger or the panel -->
-<rel-popover>
-  <span>Plain text trigger (made focusable automatically)</span>
-  <div slot="content" style="padding: 12px; background: var(--rel-bg-neutral); border: 1px solid var(--rel-border-default); border-radius: 8px;">
-    Unstyled custom panel
-  </div>
-</rel-popover>
-
-<!-- Form with focus trap: Tab cycles inside the panel until it closes -->
-<rel-popover trapfocus>
-  <rel-button>Edit profile</rel-button>
-  <rel-popover-content aria-label="Edit profile">
-    <h3>Edit profile</h3>
-    <form>
-      <rel-textfield label="Name" value="Ada Lovelace"></rel-textfield>
-      <rel-textfield label="Email" type="email" value="ada@example.com"></rel-textfield>
-      <rel-button>Save</rel-button>
-    </form>
-  </rel-popover-content>
-</rel-popover>
-
-<!-- Controlled: you own `open` and apply every requested change -->
-<rel-popover id="controlled" open>
-  <rel-button>Controlled trigger</rel-button>
-  <rel-popover-content aria-label="Controlled panel">
-    <p>State lives outside the component.</p>
-    <rel-button id="done" variant="secondary">Done</rel-button>
-  </rel-popover-content>
-</rel-popover>
-<script>
-  const popover = document.getElementById('controlled');
-  popover.addEventListener('rel-open-change', (e) => {
-    popover.open = e.detail.open;       // nothing happens until you apply it
-  });
-  document.getElementById('done').addEventListener('click', () => {
-    popover.open = false;
-  });
-  // Uncontrolled instances: never set `open`; start open with `defaultopen` instead.
-  // Default-true booleans are switched off via the property:
-  popover.closeOnOutsideClick = false;
-  popover.closeOnEscape = false;
-</script>
-```
-
-<!-- readme-gen:start -->
-
-<!-- Generated from rel-popover.ts, rel-popover-content.ts — do not edit; run readme-generate.mjs -->
-
-## Elements
-
-| Element | Class | Source |
-| --- | --- | --- |
-| `<rel-popover>` | `RelPopover` | `rel-popover.ts` |
-| `<rel-popover-content>` | `RelPopoverContent` | `rel-popover-content.ts` |
-
-## API
-
-### `<rel-popover>`
-
-#### Attributes / Properties
-
-| Property | Attribute | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| `open` | `open` | `boolean` | `undefined` | Controlled open state. Leave unset for uncontrolled mode; once set (true or false) the component only emits `rel-open-change` and you must update `open` yourself. Reflected. |
-| `defaultOpen` | `defaultopen` | `boolean` | `false` | Initial state in uncontrolled mode (attribute `defaultopen`); ignored when `open` is set. |
-| `disabled` | `disabled` | `boolean` | `false` | Blocks trigger interaction and dims the host to 60% opacity; does not close an already-open panel. Reflected. |
-| `side` | `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | Which side of the trigger the panel opens on: `top`, `right`, `bottom` (default) or `left`. The panel is clamped 8px inside the viewport but never flips to another side. Reflected. |
-| `align` | `align` | `"start" \| "center" \| "end"` | `"center"` | Alignment along the cross axis: `start` (left / top edge of the trigger), `center` (default) or `end` (right / bottom edge). Reflected. |
-| `sideOffset` | `sideoffset` | `number` | `8` | Gap between trigger and panel in pixels (attribute `sideoffset`, default 8). With `arrow` the effective gap is at least 13px. |
-| `alignOffset` | `alignoffset` | `number` | `0` | Extra shift along the alignment axis in pixels (attribute `alignoffset`, default 0); positive moves right / down. |
-| `trapFocus` | `trapfocus` | `boolean` | `false` | Keep Tab / Shift+Tab cycling inside the panel while open (attribute `trapfocus`); use for forms. |
-| `closeOnEscape` | `closeonescape` | `boolean` | `true` | Close on Escape (attribute `closeonescape`, default true; switch off via the property, e.g. `el.closeOnEscape = false`). |
-| `closeOnOutsideClick` | `closeonoutsideclick` | `boolean` | `true` | Close on a pointer-down outside the trigger and panel (attribute `closeonoutsideclick`, default true; switch off via the property). Also lets another popover's opening dismiss this one. |
-| `arrow` | `arrow` | `boolean` | `false` | Opt-in pointer (audit 23a): a 14×11 triangle on the panel edge that faces the trigger — the Figma Popover "Chevron" — following `side` and tracking the trigger's centre along the cross axis (clamped inside the panel). It is drawn with the panel's tokens (`--rel-popover-arrow-bg` / `--rel-popover-arrow-border`, defaulting to rel-popover-content's background and border). With the arrow on, the panel keeps at least the arrow's height plus 2px away from the trigger so the tip never overlaps it; larger `sideOffset` values still apply. Default off — existing popovers render exactly as before. Reflected. |
-
-### Events
-
-| Event | Detail | Bubbles / composed | Description |
-| --- | --- | --- | --- |
-| `rel-open-change` | `{ open: next }` | bubbles / composed | Fired whenever the trigger, Escape, an outside click or another popover requests a state change. Detail: `{ open: boolean }` — the requested state; in controlled mode apply it to `open` yourself. |
-
-### Slots
-
-| Slot | Description |
-| --- | --- |
-| (default) | The trigger: the first slotted element toggles the panel on pointer down / Enter / Space and receives `aria-haspopup`, `aria-expanded` and `aria-controls` (a bare `<div>` / `<span>` also gets `tabindex="0"` and `role="button"`). |
-| `content` | The panel body, usually a `<rel-popover-content>`; rendered inside the fixed, top-layer wrapper only while open. |
-
-### CSS Parts
-
-| Part | Description |
-| --- | --- |
-| `arrow` | The 14×14 chevron box rendered on the panel edge facing the trigger when `arrow` is set (absent otherwise). |
-
-### Tokens / CSS Variables
-
-#### Component hooks
-
-Set these on the host (or an ancestor) to customise the element without touching design tokens.
-
-| Custom property | Default | Description |
-| --- | --- | --- |
-| `--rel-popover-arrow-bg` | `var(--rel-bg-neutral)` | Fill of the `arrow` chevron (default `--rel-bg-neutral`, matching `<rel-popover-content>`). |
-| `--rel-popover-arrow-border` | `transparent` | **Deprecated.** Stroke of the `arrow` chevron's two slanted edges. The panel no longer draws a border — overlapping surfaces are separated by shadow — so this defaults to `transparent` and the chevron has no edge. Set it to restore a stroke. |
-
-### `<rel-popover-content>`
-
-#### Attributes / Properties
-
-| Property | Attribute | Type | Default | Description |
-| --- | --- | --- | --- | --- |
-| `ariaLabel` | `aria-label` | `string` | `""` | Accessible name applied to the inner `role="dialog"` box (attribute `aria-label`); describe what the panel is for. |
-| `size` | `size` | `"small" \| "medium" \| "large" \| "sm" \| "md" \| "lg"` | `"medium"` | Figma Size axis: panel padding 12px (`small`), 16px (`medium`, default) or 20px (`large`). `sm` / `md` / `lg` are alternative spellings and stay supported — they are normalised to the full words, not deprecated. Reflected. |
-
-### Events
-
-| Event | Detail | Bubbles / composed | Description |
-| --- | --- | --- | --- |
-| — | — | — | This element emits no custom events. |
-
-### Slots
-
-| Slot | Description |
-| --- | --- |
-| (default) | The panel content (headings, paragraphs, form controls, buttons). |
-
-### CSS Parts
-
-| Part | Description |
-| --- | --- |
-| `content` | The padded `role="dialog"` box that carries the surface, border, shadow and size padding. |
-
-<!-- readme-gen:end -->
-
-## Accessibility
-
-- The trigger (first slotted element) is decorated with `aria-haspopup="dialog"`, `aria-expanded` (kept in sync with the open state) and `aria-controls` pointing at the panel wrapper. A trigger that is not natively focusable and contains nothing focusable (a bare `<div>` / `<span>`) also gets `tabindex="0"` and `role="button"`; native buttons and `<rel-button>` are left alone so they do not get a second Tab stop.
-- `<rel-popover-content>` renders its box with `role="dialog"`; pass `aria-label` so the dialog has a name. A custom panel element should carry its own role and label.
-- On open, focus moves to the first focusable element inside the panel (links, enabled buttons and inputs, positive `tabindex`), or to the panel wrapper when there is none. On close, focus returns to whatever was focused before opening (normally the trigger).
-- With `trapfocus`, Tab from the last focusable element wraps to the first and Shift+Tab from the first wraps to the last, so keyboard focus cannot leave the panel while it is open. Without it, Tab leaves the panel normally and the panel stays open until an outside click or Escape.
-- There are no screen-reader announcements beyond the `aria-expanded` change; put the important content first in the panel so it is read when focus lands.
-
-| Key | Action |
-| --- | --- |
-| `Enter` / `Space` (on the trigger) | Toggle the panel |
-| `Escape` (anywhere, while open) | Close (unless `closeOnEscape` is switched off) |
-| `Tab` / `Shift+Tab` | Move through the panel's focusable elements; with `trapfocus` the order wraps at both ends |
-
-## Notes / Edge Cases
-
-- **Slots.** The trigger is the *default* slot's first element; the panel goes in `slot="content"`. There is no `trigger` slot. Only one element should be in the default slot — extra default-slot children render next to the trigger but never toggle the panel.
-- **Top layer / inside a modal.** The panel wrapper is a native `popover="manual"` element shown with `showPopover()`, so a transformed or `overflow: hidden` ancestor (for example `<rel-modal>`'s centred panel) cannot clip it or break its `position: fixed` coordinates. Where the Popover API is unavailable it falls back to `position: fixed; z-index: 1001` and re-measures once to cancel any containing-block offset.
-- **No collision flipping.** The panel always opens on the requested `side`; it is only clamped to stay 8px inside the viewport. Pick the side yourself for edge-of-screen triggers.
-- **One open at a time.** Opening a popover light-dismisses every other open popover that honours `closeOnOutsideClick`, whether it was opened by pointer, keyboard or code. A popover nested inside another's panel keeps its parent open.
-- **Controlled vs uncontrolled.** `open` is `undefined` until you set it; setting it (to `true` *or* `false`) switches the instance to controlled mode permanently, after which the component only emits `rel-open-change` and never changes its own state. Use `defaultopen` for an uncontrolled popover that starts open.
-- **Default-true booleans** (`closeOnEscape`, `closeOnOutsideClick`) cannot be turned off with an attribute — a boolean attribute is true whenever present. Set the property instead.
-- **Positioning updates** run on window resize and on scroll (capture phase). They do not run when the panel's own content changes size; toggle `open` or trigger a resize if you swap content while open.
-- **Arrow.** `arrow` draws a 14×11 chevron on the panel edge facing the trigger, centred on the trigger and clamped 15px in from the panel corners; the trigger gap becomes `max(sideoffset, 13px)`. Colour it with `--rel-popover-arrow-bg` / `--rel-popover-arrow-border` (defaults match `<rel-popover-content>`); if you use a custom panel with a different surface, set both so the chevron blends in.
-- **`<rel-popover-content>`** is `display: block; width: 100%; max-width: 400px`; override `max-width` on the element for wider panels. Slotted `h1`–`h6` get heading-sm type and `p` gets placeholder-tone body text with a bottom margin (none on the last paragraph).
-- **`disabled`** blocks the trigger and dims the host but does not close a panel that is already open — set `open = false` first if needed.
-- The `size` values on `<rel-popover-content>` are `small` / `medium` / `large`. The short spellings `sm` / `md` / `lg` are alternative spellings and keep working — they are normalised to the full words before the attribute reflects, so `rel-popover-content[size="medium"]` matches whichever spelling was written.
+# rel-popover
+
+A click-to-open floating panel anchored to a trigger, implementing the Figma "Popover" component (including its opt-in chevron). The folder registers two elements: `<rel-popover>` is the controller — its first child is the trigger, its `content` slot is the panel — and `<rel-popover-content>` is the optional styled surface (neutral background, radius, shadow, S/M/L padding; no border) you drop into that slot. The panel is promoted to the browser top layer and positioned in viewport coordinates, so it renders correctly even inside a centred `<rel-modal>`. Use it for rich, interactive content that needs an explicit click — small forms, filters, menus, detail cards. For a short hover label use `<rel-tooltip>`; for a task that must be completed before continuing use `<rel-modal>`.
+
+## Usage
+
+```html
+<!-- Basic: first child = trigger, slot="content" = panel -->
+<rel-popover>
+  <rel-button>Open</rel-button>
+  <rel-popover-content aria-label="About popovers">
+    <h3>Popover title</h3>
+    <p>Any HTML can go here.</p>
+  </rel-popover-content>
+</rel-popover>
+
+<!-- Panel padding (Figma Size S / M / L = 12 / 16 / 20px) -->
+<rel-popover>
+  <rel-button variant="secondary">Compact</rel-button>
+  <rel-popover-content size="small" aria-label="Compact panel"><p>12px padding</p></rel-popover-content>
+</rel-popover>
+<rel-popover>
+  <rel-button variant="secondary">Roomy</rel-button>
+  <rel-popover-content size="large" aria-label="Roomy panel"><p>20px padding</p></rel-popover-content>
+</rel-popover>
+
+<!-- Positioning: side, alignment and pixel offsets -->
+<rel-popover side="top" align="start">
+  <rel-button>Top / start</rel-button>
+  <rel-popover-content aria-label="Top start"><p>Above the trigger, left edges aligned.</p></rel-popover-content>
+</rel-popover>
+<rel-popover side="right" side-offset="16" align-offset="8">
+  <rel-button>Right, 16px away</rel-button>
+  <rel-popover-content aria-label="Right offset"><p>16px gap, shifted 8px down.</p></rel-popover-content>
+</rel-popover>
+
+<!-- Chevron pointing at the trigger -->
+<rel-popover side="bottom" arrow>
+  <rel-button>With arrow</rel-button>
+  <rel-popover-content aria-label="Arrow demo"><p>The chevron follows the trigger centre.</p></rel-popover-content>
+</rel-popover>
+
+<!-- Any element can be the trigger or the panel -->
+<rel-popover>
+  <span>Plain text trigger (made focusable automatically)</span>
+  <div slot="content" style="padding: 12px; background: var(--rel-bg-neutral); border: 1px solid var(--rel-border-default); border-radius: 8px;">
+    Unstyled custom panel
+  </div>
+</rel-popover>
+
+<!-- Form with focus trap: Tab cycles inside the panel until it closes -->
+<rel-popover trap-focus>
+  <rel-button>Edit profile</rel-button>
+  <rel-popover-content aria-label="Edit profile">
+    <h3>Edit profile</h3>
+    <form>
+      <rel-textfield label="Name" value="Ada Lovelace"></rel-textfield>
+      <rel-textfield label="Email" type="email" value="ada@example.com"></rel-textfield>
+      <rel-button>Save</rel-button>
+    </form>
+  </rel-popover-content>
+</rel-popover>
+
+<!-- Controlled: you own `open` and apply every requested change -->
+<rel-popover id="controlled" open>
+  <rel-button>Controlled trigger</rel-button>
+  <rel-popover-content aria-label="Controlled panel">
+    <p>State lives outside the component.</p>
+    <rel-button id="done" variant="secondary">Done</rel-button>
+  </rel-popover-content>
+</rel-popover>
+<script>
+  const popover = document.getElementById('controlled');
+  popover.addEventListener('rel-open-change', (e) => {
+    popover.open = e.detail.open;       // nothing happens until you apply it
+  });
+  document.getElementById('done').addEventListener('click', () => {
+    popover.open = false;
+  });
+  // Uncontrolled instances: never set `open`; start open with `default-open` instead.
+  // Default-true booleans are switched off via the property:
+  popover.closeOnOutsideClick = false;
+  popover.closeOnEscape = false;
+</script>
+```
+
+### Deprecated aliases
+
+```html
+<!-- Lowercase-joined attribute spellings → kebab-case (since 1.5.0; still work, log a one-time
+     console notice, removed in 3.0) -->
+<rel-popover defaultopen sideoffset="16" alignoffset="8" trapfocus closeonescape="false" closeonoutsideclick="false">…</rel-popover>
+<!-- canonical -->
+<rel-popover default-open side-offset="16" align-offset="8" trap-focus close-on-escape="false" close-on-outside-click="false">…</rel-popover>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-popover.ts, rel-popover-content.ts — do not edit; run readme-generate.mjs -->
+
+## Elements
+
+| Element | Class | Source |
+| --- | --- | --- |
+| `<rel-popover>` | `RelPopover` | `rel-popover.ts` |
+| `<rel-popover-content>` | `RelPopoverContent` | `rel-popover-content.ts` |
+
+## API
+
+### `<rel-popover>`
+
+#### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `open` | `open` | `boolean` | `undefined` | Controlled open state. Leave unset for uncontrolled mode; once set (true or false) the component only emits `rel-open-change` and you must update `open` yourself. Reflected. |
+| `defaultOpen` | `default-open` | `boolean` | `false` | Initial state in uncontrolled mode (attribute `default-open`); ignored when `open` is set. The `defaultopen` attribute spelling is deprecated (still works; removal targeted for 3.0). |
+| `disabled` | `disabled` | `boolean` | `false` | Blocks trigger interaction and dims the host to 60% opacity; does not close an already-open panel. Reflected. |
+| `side` | `side` | `"top" \| "right" \| "bottom" \| "left"` | `"bottom"` | Which side of the trigger the panel opens on: `top`, `right`, `bottom` (default) or `left`. The panel is clamped 8px inside the viewport but never flips to another side. Reflected. |
+| `align` | `align` | `"start" \| "center" \| "end"` | `"center"` | Alignment along the cross axis: `start` (left / top edge of the trigger), `center` (default) or `end` (right / bottom edge). Reflected. |
+| `sideOffset` | `side-offset` | `number` | `8` | Gap between trigger and panel in pixels (attribute `side-offset`, default 8). With `arrow` the effective gap is at least 13px. The `sideoffset` attribute spelling is deprecated (still works; removal targeted for 3.0). |
+| `alignOffset` | `align-offset` | `number` | `0` | Extra shift along the alignment axis in pixels (attribute `align-offset`, default 0); positive moves right / down. The `alignoffset` attribute spelling is deprecated (still works; removal targeted for 3.0). |
+| `trapFocus` | `trap-focus` | `boolean` | `false` | Keep Tab / Shift+Tab cycling inside the panel while open (attribute `trap-focus`); use for forms. The `trapfocus` attribute spelling is deprecated (still works; removal targeted for 3.0). |
+| `closeOnEscape` | `close-on-escape` | `boolean` | `true` | Close on Escape (attribute `close-on-escape`, default true; switch off with `close-on-escape="false"` or `el.closeOnEscape = false`). The `closeonescape` attribute spelling is deprecated (still works; removal targeted for 3.0). |
+| `closeOnOutsideClick` | `close-on-outside-click` | `boolean` | `true` | Close on a pointer-down outside the trigger and panel (attribute `close-on-outside-click`, default true; switch off with `close-on-outside-click="false"` or the property). Also lets another popover's opening dismiss this one. The `closeonoutsideclick` attribute spelling is deprecated (still works; removal targeted for 3.0). |
+| `arrow` | `arrow` | `boolean` | `false` | Opt-in pointer (audit 23a): a 14×11 triangle on the panel edge that faces the trigger — the Figma Popover "Chevron" — following `side` and tracking the trigger's centre along the cross axis (clamped inside the panel). It is drawn with the panel's tokens (`--rel-popover-arrow-bg` / `--rel-popover-arrow-border`, defaulting to rel-popover-content's background and border). With the arrow on, the panel keeps at least the arrow's height plus 2px away from the trigger so the tip never overlaps it; larger `sideOffset` values still apply. Default off — existing popovers render exactly as before. Reflected. |
+| `hasPopup` | `has-popup` | `"dialog" \| "menu" \| "listbox" \| "tree" \| "grid" \| "true"` | `"dialog"` | New in 1.5.0. Value written to the trigger's `aria-haspopup` (attribute `has-popup`): `dialog` (default) for a panel of content, or `menu`, `listbox`, `tree`, `grid` or `true` when the panel holds that widget. A panel holding a `rel-menu` takes `menu`. |
+
+### Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| `rel-open-change` | `{ open: next }` | bubbles / composed | Fired whenever the trigger, Escape, an outside click or another popover requests a state change. Detail: `{ open: boolean }` — the requested state; in controlled mode apply it to `open` yourself. |
+
+### Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | The trigger: the first slotted element toggles the panel on pointer down / Enter / Space and receives `aria-haspopup` (from `has-popup`), `aria-expanded` and `aria-controls` (a bare `<div>` / `<span>` also gets `tabindex="0"` and `role="button"`). |
+| `content` | The panel body, usually a `<rel-popover-content>`; rendered inside the fixed, top-layer wrapper only while open. |
+
+### CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `arrow` | The 14×14 chevron box rendered on the panel edge facing the trigger when `arrow` is set (absent otherwise). |
+
+### Tokens / CSS Variables
+
+#### Component hooks
+
+Set these on the host (or an ancestor) to customise the element without touching design tokens.
+
+| Custom property | Default | Description |
+| --- | --- | --- |
+| `--rel-popover-arrow-bg` | `var(--rel-bg-neutral)` | Fill of the `arrow` chevron (default `--rel-bg-neutral`, matching `<rel-popover-content>`). |
+| `--rel-popover-arrow-border` | `transparent` | **Deprecated.** Stroke of the `arrow` chevron's two slanted edges. The panel no longer draws a border — overlapping surfaces are separated by shadow — so this defaults to `transparent` and the chevron has no edge. Set it to restore a stroke. |
+
+### `<rel-popover-content>`
+
+#### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `ariaLabel` | `aria-label` | `string` | `""` | Accessible name applied to the inner `role="dialog"` box (attribute `aria-label`); describe what the panel is for. |
+| `size` | `size` | `"small" \| "medium" \| "large" \| "sm" \| "md" \| "lg"` | `"medium"` | Figma Size axis: panel padding 12px (`small`), 16px (`medium`, default) or 20px (`large`). `sm` / `md` / `lg` are alternative spellings and stay supported — they are normalised to the full words, not deprecated. Reflected. |
+
+#### Methods
+
+| Method | Signature | Description |
+| --- | --- | --- |
+| `focus` | `focus(options?: FocusOptions)` | Focuses the `role="dialog"` box rather than the host (which is not focusable). rel-popover lands focus here when the panel has nothing focusable, so a screen reader announces the dialog by its `aria-label`. |
+
+### Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+### Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | The panel content (headings, paragraphs, form controls, buttons). |
+
+### CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `content` | The padded `role="dialog"` box that carries the surface, shadow and size padding. |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- The trigger (first slotted element) is decorated with `aria-haspopup="dialog"`, `aria-expanded` (kept in sync with the open state) and `aria-controls` pointing at the panel wrapper. A trigger that is not natively focusable and contains nothing focusable (a bare `<div>` / `<span>`) also gets `tabindex="0"` and `role="button"`; native buttons and `<rel-button>` are left alone so they do not get a second Tab stop.
+- `<rel-popover-content>` renders its box with `role="dialog"`; pass `aria-label` so the dialog has a name. A custom panel element should carry its own role and label.
+- On open, focus moves to the first focusable element inside the panel — found through slots and nested shadow roots, so a `<rel-button>` inside `<rel-popover-content>` counts. When there is none, the panel itself takes focus so it is announced: `<rel-popover-content>` focuses its `role="dialog"` box (named by its `aria-label`), and any other panel element falls back to the panel wrapper. On close, focus that was inside the popover returns to the trigger's own control (a `<rel-button>`'s inner `<button>`); a close while focus is elsewhere on the page leaves it there.
+- With `trap-focus`, Tab from the last focusable element wraps to the first and Shift+Tab from the first wraps to the last, so keyboard focus cannot leave the panel while it is open. Without it, Tab leaves the panel normally and the panel stays open until an outside click or Escape.
+- There are no screen-reader announcements beyond the `aria-expanded` change; put the important content first in the panel so it is read when focus lands.
+
+| Key | Action |
+| --- | --- |
+| `Enter` / `Space` (on the trigger) | Toggle the panel |
+| `Escape` (anywhere, while open) | Close (unless `closeOnEscape` is switched off) |
+| `Tab` / `Shift+Tab` | Move through the panel's focusable elements; with `trap-focus` the order wraps at both ends |
+
+## Notes / Edge Cases
+
+- **Slots.** The trigger is the *default* slot's first element; the panel goes in `slot="content"`. There is no `trigger` slot. Only one element should be in the default slot — extra default-slot children render next to the trigger but never toggle the panel.
+- **Top layer / inside a modal.** The panel wrapper is a native `popover="manual"` element shown with `showPopover()`, so a transformed or `overflow: hidden` ancestor (for example `<rel-modal>`'s centred panel) cannot clip it or break its `position: fixed` coordinates. Where the Popover API is unavailable it falls back to `position: fixed; z-index: 1001` and re-measures once to cancel any containing-block offset.
+- **No collision flipping.** The panel always opens on the requested `side`; it is only clamped to stay 8px inside the viewport. Pick the side yourself for edge-of-screen triggers.
+- **One open at a time.** Opening a popover light-dismisses every other open popover that honours `closeOnOutsideClick`, whether it was opened by pointer, keyboard or code. A popover nested inside another's panel keeps its parent open.
+- **Controlled vs uncontrolled.** `open` is `undefined` until you set it; setting it (to `true` *or* `false`) switches the instance to controlled mode permanently, after which the component only emits `rel-open-change` and never changes its own state. Use `default-open` for an uncontrolled popover that starts open.
+- **Default-true booleans** (`closeOnEscape`, `closeOnOutsideClick`): since 1.5.0 the attribute value `"false"` turns them off (`close-on-escape="false"`), as does setting the property. A bare attribute or `=""` still means true.
+- **Positioning updates** run on window resize and on scroll (capture phase). They do not run when the panel's own content changes size; toggle `open` or trigger a resize if you swap content while open.
+- **Arrow.** `arrow` draws a 14×11 chevron on the panel edge facing the trigger, centred on the trigger and clamped 15px in from the panel corners; the trigger gap becomes `max(side-offset, 13px)`. Colour it with `--rel-popover-arrow-bg` / `--rel-popover-arrow-border` (defaults match `<rel-popover-content>`); if you use a custom panel with a different surface, set both so the chevron blends in.
+- **`<rel-popover-content>`** is `display: block; width: 100%; max-width: 400px`; override `max-width` on the element for wider panels. Slotted `h1`–`h6` get heading-sm type and `p` gets placeholder-tone body text with a bottom margin (none on the last paragraph).
+- **`disabled`** blocks the trigger and dims the host but does not close a panel that is already open — set `open = false` first if needed.
+- The `size` values on `<rel-popover-content>` are `small` / `medium` / `large`. The short spellings `sm` / `md` / `lg` are alternative spellings and keep working — they are normalised to the full words before the attribute reflects, so `rel-popover-content[size="medium"]` matches whichever spelling was written.