@reliability-design/web 1.4.5 → 1.4.7

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

@@ -1,568 +1,203 @@
-# rel-popover
-
-A flexible popover component that displays rich content anchored to a trigger element. Features smart positioning with collision detection, controlled and uncontrolled modes, focus management, and accessibility support.
-
-## What It Is
-
-The popover consists of two custom elements:
-- `<rel-popover>` - Root controller that manages state, positioning, and interactions
-- `<rel-popover-content>` - Optional styled container for popover content with consistent design tokens
-
-## Basic Usage
-
-```html
-<rel-popover>
-  <button slot="trigger">Open Popover</button>
-  <rel-popover-content>
-    <h3>Popover Title</h3>
-    <p>This is the popover content. It can contain any HTML elements.</p>
-  </rel-popover-content>
-</rel-popover>
-```
-
-## Controlled Mode
-
-Control the open state externally:
-
-```html
-<rel-popover id="my-popover" open>
-  <button slot="trigger">Open Popover</button>
-  <rel-popover-content>
-    <p>Controlled popover content</p>
-    <button data-popover-close>Close</button>
-  </rel-popover-content>
-</rel-popover>
-
-<script>
-  const popover = document.getElementById('my-popover');
-
-  // Listen to open state changes
-  popover.addEventListener('rel-open-change', (e) => {
-    console.log('Popover is now:', e.detail.open ? 'open' : 'closed');
-
-    // Update external state
-    // You control when to update the 'open' attribute
-  });
-
-  // Programmatically control
-  document.getElementById('external-btn').addEventListener('click', () => {
-    popover.open = true;
-  });
-</script>
-```
-
-## Positioning Options
-
-```html
-<!-- Position above trigger, aligned to start -->
-<rel-popover side="top" align="start">
-  <button slot="trigger">Top Start</button>
-  <rel-popover-content>
-    <p>Positioned above, aligned to start</p>
-  </rel-popover-content>
-</rel-popover>
-
-<!-- Position to the right with offset -->
-<rel-popover side="right" sideOffset="16" alignOffset="8">
-  <button slot="trigger">Right with Offset</button>
-  <rel-popover-content>
-    <p>Positioned to right with custom spacing</p>
-  </rel-popover-content>
-</rel-popover>
-```
-
-## Form Example with Focus Trap
-
-```html
-<rel-popover trapFocus>
-  <button slot="trigger">Edit Profile</button>
-  <rel-popover-content aria-label="Edit profile form">
-    <h3>Edit Profile</h3>
-    <form>
-      <label>
-        Name:
-        <input type="text" value="John Doe" />
-      </label>
-      <label>
-        Email:
-        <input type="email" value="john@example.com" />
-      </label>
-      <div style="display: flex; gap: 8px; margin-top: 12px;">
-        <button type="submit">Save</button>
-        <button type="button" data-popover-close>Cancel</button>
-      </div>
-    </form>
-  </rel-popover-content>
-</rel-popover>
-```
-
-## API Reference
-
-### rel-popover
-
-Root controller component that manages popover behavior.
-
-**Attributes:**
-
-- `open` (boolean, optional) - Controlled open state. When set, component is in controlled mode
-- `defaultOpen` (boolean) - Initial open state for uncontrolled mode, default: `false`
-- `disabled` (boolean) - Disables the popover, default: `false`
-- `side` ("top" | "right" | "bottom" | "left") - Preferred side to position popover, default: `"bottom"`
-- `align` ("start" | "center" | "end") - Alignment relative to trigger, default: `"center"`
-- `sideOffset` (number) - Distance from trigger in pixels, default: `8`
-- `alignOffset` (number) - Offset along the alignment axis in pixels, default: `0`
-- `trapFocus` (boolean) - Trap focus within popover (useful for forms), default: `false`
-- `closeOnEscape` (boolean) - Close when Escape key is pressed, default: `true`
-- `closeOnOutsideClick` (boolean) - Close when clicking outside, default: `true`
-
-**Events:**
-
-- `rel-open-change` - Emitted when open state changes
-  ```typescript
-  detail: { open: boolean }
-  ```
-
-**Slots:**
-
-- `trigger` (named) - The trigger element (usually a button)
-- Default slot - The popover content
-
-**Example:**
-```javascript
-const popover = document.querySelector('rel-popover');
-
-// Listen to state changes
-popover.addEventListener('rel-open-change', (e) => {
-  console.log('Open:', e.detail.open);
-});
-
-// Programmatic control (controlled mode)
-popover.open = true;
-```
-
-### rel-popover-content
-
-Styled container for popover content with consistent design tokens.
-
-**Attributes:**
-
-- `aria-label` (string) - Accessible label for the popover dialog
-
-**Usage:**
-```html
-<rel-popover-content aria-label="User settings">
-  <h3>Settings</h3>
-  <p>Configure your preferences</p>
-</rel-popover-content>
-```
-
-**Styling:**
-The content component provides consistent styling:
-- White background with border and shadow
-- Proper padding and spacing
-- Heading and paragraph styles with design tokens
-- Maximum width of 400px (can be overridden)
-
-**Custom Content:**
-You don't have to use `rel-popover-content`. Any HTML can go in the default slot:
-```html
-<rel-popover>
-  <button slot="trigger">Open</button>
-  <div class="my-custom-popover">
-    Custom styled content
-  </div>
-</rel-popover>
-```
-
-## Controlled vs Uncontrolled
-
-### Uncontrolled (Default)
-Component manages its own open state:
-```html
-<rel-popover defaultOpen>
-  <button slot="trigger">Toggle</button>
-  <rel-popover-content>Content</rel-popover-content>
-</rel-popover>
-```
-
-The component will:
-- Toggle open/close when trigger is clicked
-- Emit `rel-open-change` events
-- Update its internal state automatically
-
-### Controlled
-You manage the open state externally:
-```html
-<rel-popover id="controlled" open="${this.isOpen}">
-  <button slot="trigger">Toggle</button>
-  <rel-popover-content>Content</rel-popover-content>
-</rel-popover>
-
-<script>
-  let isOpen = false;
-  const popover = document.getElementById('controlled');
-
-  popover.addEventListener('rel-open-change', (e) => {
-    isOpen = e.detail.open;
-    popover.open = isOpen; // Update the attribute
-  });
-</script>
-```
-
-When `open` attribute is set, the component:
-- Will NOT update its own state
-- Emits `rel-open-change` events
-- You must update the `open` attribute in response to events
-
-## Positioning Behavior
-
-The popover uses smart positioning with collision detection:
-
-### Side Preference
-Specify the preferred side with the `side` attribute:
-- `"bottom"` (default) - Opens below trigger
-- `"top"` - Opens above trigger
-- `"right"` - Opens to the right
-- `"left"` - Opens to the left
-
-### Collision Detection
-If the popover would overflow the viewport, it automatically flips to the opposite side:
-- Bottom → Top (if more space above)
-- Top → Bottom (if more space below)
-- Right → Left (if more space on left)
-- Left → Right (if more space on right)
-
-### Alignment
-Control how the popover aligns to its trigger:
-
-For top/bottom sides:
-- `"start"` - Aligns to left edge of trigger
-- `"center"` (default) - Centers horizontally
-- `"end"` - Aligns to right edge of trigger
-
-For left/right sides:
-- `"start"` - Aligns to top edge of trigger
-- `"center"` (default) - Centers vertically
-- `"end"` - Aligns to bottom edge of trigger
-
-### Offsets
-Fine-tune positioning with offsets:
-- `sideOffset` - Distance from trigger (default: 8px)
-- `alignOffset` - Shift along alignment axis (default: 0)
-
-```html
-<!-- 16px away from trigger, shifted 8px to the right -->
-<rel-popover side="bottom" sideOffset="16" alignOffset="8">
-  <button slot="trigger">Custom Offset</button>
-  <rel-popover-content>Content</rel-popover-content>
-</rel-popover>
-```
-
-### Dynamic Repositioning
-The popover automatically repositions when:
-- Window is resized
-- Page is scrolled
-- Popover content size changes
-
-## Close Triggers
-
-The popover can close in several ways:
-
-1. **Click Outside** (default enabled)
-   - Click anywhere outside the popover
-   - Controlled by `closeOnOutsideClick` attribute
-
-2. **Escape Key** (default enabled)
-   - Press Escape to close
-   - Controlled by `closeOnEscape` attribute
-
-3. **Close Button**
-   - Add `data-popover-close` to any element
-   ```html
-   <button data-popover-close>Close</button>
-   <button type="button" data-popover-close>Cancel</button>
-   ```
-
-4. **Programmatic**
-   ```javascript
-   popover.open = false;
-   ```
-
-## Focus Management
-
-### Default Behavior
-When popover opens:
-1. Saves currently focused element
-2. Focuses first focusable element in popover
-3. Returns focus to trigger when closed
-
-### Focus Trap
-Enable focus trapping for forms and modal-like behavior:
-```html
-<rel-popover trapFocus>
-  <button slot="trigger">Edit</button>
-  <rel-popover-content>
-    <form>
-      <input type="text" />
-      <button>Save</button>
-      <button data-popover-close>Cancel</button>
-    </form>
-  </rel-popover-content>
-</rel-popover>
-```
-
-With `trapFocus` enabled:
-- Tab cycles through focusable elements
-- When reaching last element, Tab wraps to first
-- Shift+Tab cycles backward
-- Cannot tab out of the popover
-
-## Keyboard Navigation
-
-| Key | Action |
-|-----|--------|
-| `Click Trigger` | Toggle popover open/close |
-| `Escape` | Close popover (if `closeOnEscape` is true) |
-| `Tab` | Move to next focusable element |
-| `Shift + Tab` | Move to previous focusable element |
-| `Tab` (with `trapFocus`) | Cycle through elements, wrapping at edges |
-
-## Accessibility
-
-The component implements WCAG accessibility guidelines:
-
-### ARIA Attributes
-- Trigger has `aria-haspopup="dialog"`
-- Trigger has `aria-expanded` reflecting open state
-- Trigger has `aria-controls` pointing to content
-- Content has `role="dialog"`
-- Content can have `aria-label` for screen readers
-
-### Focus Management
-- Automatically focuses first focusable element
-- Returns focus to trigger on close
-- Optional focus trapping for modal behavior
-
-### Keyboard Support
-- Full keyboard navigation
-- Escape key to close
-- Tab navigation through content
-
-### Best Practices
-```html
-<!-- Good: Descriptive trigger and labeled content -->
-<rel-popover>
-  <button slot="trigger" aria-label="Open user settings">
-    <svg>...</svg>
-  </button>
-  <rel-popover-content aria-label="User settings">
-    <h3>Settings</h3>
-    <!-- ... -->
-  </rel-popover-content>
-</rel-popover>
-
-<!-- Good: Close button with clear label -->
-<button type="button" data-popover-close aria-label="Close settings">
-  ×
-</button>
-```
-
-## Styling Tokens
-
-The component uses design tokens from the Reliability Design System:
-
-### Colors (rel-popover-content)
-- `--rel-bg-surface` - Content background
-- `--rel-border-default` - Border color
-- `--rel-text-label` - Text color
-- `--rel-text-placeholder` - Paragraph text color
-
-### Typography
-- `--rel-fonts-font-family` - Font family (Poppins)
-- `--rel-fonts-weight-body-semibold` - Heading weight
-- `--rel-body-sm-regular-font-size` - Base text size
-- `--rel-body-md-regular-line-height` - Paragraph line height
-
-### Spacing
-- `--rel-spacing-md` (16px) - Content padding
-- `--rel-spacing-xs` (8px) - Heading bottom margin
-- `--rel-spacing-sm` (12px) - Paragraph bottom margin
-
-### Borders & Effects
-- `--rel-stroke-sm` (1px) - Border width
-- `--rel-border-radius-sm` (8px) - Border radius
-- `--rel-shadows-shadow-300` - Drop shadow
-
-### Z-Index
-- Popover content: `z-index: 1001`
-
-### Custom Styling
-Use CSS parts to style the component:
-```css
-/* Style the trigger wrapper */
-rel-popover::part(trigger) {
-  display: block;
-  width: 100%;
-}
-
-/* Style the content wrapper */
-rel-popover::part(content-wrapper) {
-  /* Custom styles */
-}
-
-/* Style the content container */
-rel-popover-content::part(content) {
-  max-width: 600px;
-  padding: 24px;
-}
-```
-
-## Complete Example
-
-```html
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Popover Demo</title>
-  <script type="module" src="./dist/index.js"></script>
-</head>
-<body>
-  <div style="padding: 100px;">
-    <!-- Basic Popover -->
-    <rel-popover id="basic-popover">
-      <button slot="trigger">Open Popover</button>
-      <rel-popover-content aria-label="Information">
-        <h3>About Popovers</h3>
-        <p>Popovers are floating containers that display rich content anchored to a trigger element.</p>
-        <button data-popover-close>Got it</button>
-      </rel-popover-content>
-    </rel-popover>
-
-    <!-- Positioning Variations -->
-    <rel-popover side="top" align="start">
-      <button slot="trigger">Top Start</button>
-      <rel-popover-content>
-        <p>Positioned above, aligned to start</p>
-      </rel-popover-content>
-    </rel-popover>
-
-    <rel-popover side="right" align="center">
-      <button slot="trigger">Right Center</button>
-      <rel-popover-content>
-        <p>Positioned to the right, centered</p>
-      </rel-popover-content>
-    </rel-popover>
-
-    <!-- Form with Focus Trap -->
-    <rel-popover id="form-popover" trapFocus>
-      <button slot="trigger">Edit Profile</button>
-      <rel-popover-content aria-label="Edit profile form">
-        <h3>Edit Profile</h3>
-        <form id="profile-form">
-          <div style="margin-bottom: 12px;">
-            <label>
-              Name:<br>
-              <input type="text" name="name" value="John Doe" style="width: 100%;">
-            </label>
-          </div>
-          <div style="margin-bottom: 12px;">
-            <label>
-              Email:<br>
-              <input type="email" name="email" value="john@example.com" style="width: 100%;">
-            </label>
-          </div>
-          <div style="display: flex; gap: 8px;">
-            <button type="submit">Save</button>
-            <button type="button" data-popover-close>Cancel</button>
-          </div>
-        </form>
-      </rel-popover-content>
-    </rel-popover>
-
-    <!-- Controlled Mode -->
-    <div>
-      <button id="external-open">Open Controlled Popover</button>
-      <button id="external-close">Close Controlled Popover</button>
-      <p>State: <span id="state-display">closed</span></p>
-
-      <rel-popover id="controlled-popover">
-        <button slot="trigger">Controlled Trigger</button>
-        <rel-popover-content>
-          <h3>Controlled Popover</h3>
-          <p>This popover's state is controlled externally.</p>
-          <button data-popover-close>Close</button>
-        </rel-popover-content>
-      </rel-popover>
-    </div>
-  </div>
-
-  <script>
-    // Event logging
-    document.getElementById('basic-popover').addEventListener('rel-open-change', (e) => {
-      console.log('Basic popover:', e.detail.open ? 'opened' : 'closed');
-    });
-
-    // Form handling
-    document.getElementById('profile-form').addEventListener('submit', (e) => {
-      e.preventDefault();
-      const formData = new FormData(e.target);
-      console.log('Saved:', Object.fromEntries(formData));
-      document.getElementById('form-popover').open = false;
-    });
-
-    // Controlled mode
-    const controlledPopover = document.getElementById('controlled-popover');
-    const stateDisplay = document.getElementById('state-display');
-
-    let isOpen = false;
-
-    controlledPopover.addEventListener('rel-open-change', (e) => {
-      isOpen = e.detail.open;
-      controlledPopover.open = isOpen;
-      stateDisplay.textContent = isOpen ? 'open' : 'closed';
-    });
-
-    document.getElementById('external-open').addEventListener('click', () => {
-      isOpen = true;
-      controlledPopover.open = isOpen;
-      stateDisplay.textContent = 'open';
-    });
-
-    document.getElementById('external-close').addEventListener('click', () => {
-      isOpen = false;
-      controlledPopover.open = isOpen;
-      stateDisplay.textContent = 'closed';
-    });
-  </script>
-</body>
-</html>
-```
-
-## Browser Support
-
-Compatible with all modern browsers supporting:
-- Web Components (Custom Elements v1)
-- Shadow DOM
-- ES2020+ features
-- ResizeObserver API
-
-## Framework Integration
-
-Works seamlessly with:
-- Vanilla JavaScript
-- Angular
-- React (via wrapper)
-- Vue
-- Any framework supporting Web Components
-
-## Comparison with Tooltip
-
-While `rel-tooltip` is for brief labels on hover, `rel-popover` is for:
-- **Rich interactive content** - Forms, menus, complex layouts
-- **Explicit user action** - Click to open (not hover)
-- **Focus management** - Can trap focus for forms
-- **Controlled state** - External state management support
-
-Use `rel-tooltip` for simple labels, use `rel-popover` for interactive content.
+# 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="sm" 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="lg" 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` | `var(--rel-border-default)` | Stroke of the `arrow` chevron's two slanted edges (default `--rel-border-default`). |
+
+### `<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` | `"sm" \| "md" \| "lg"` | `"md"` | Figma Size axis (S/M/L): panel padding 12/16/20px. 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 the short spellings `sm` / `md` / `lg`; there are no full-word aliases on this element.