@reliability-design/web 1.0.2 → 1.0.6

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

@@ -0,0 +1,568 @@
+# 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-colors-white` - Content background
+- `--rel-colors-gray-border` - Border color
+- `--rel-colors-gray-heading` - Text color
+- `--rel-colors-gray-placeholder` - Paragraph text color
+
+### Typography
+- `--rel-fontFamilies-primary` - Font family (Poppins)
+- `--rel-fontWeights-semibold` - Heading weight
+- `--rel-fontSizes-sm` - Base text size
+- `--rel-lineHeights-md` - Paragraph line height
+
+### Spacing
+- `--rel-spacing-space-md` (16px) - Content padding
+- `--rel-spacing-space-xs` (8px) - Heading bottom margin
+- `--rel-spacing-space-sm` (12px) - Paragraph bottom margin
+
+### Borders & Effects
+- `--rel-borders-width-stroke-100` (1px) - Border width
+- `--rel-borders-radius-border-radius-200` (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.

package/dist/components/rel-popover/index.ts

@@ -0,0 +1,2 @@
+export * from "./rel-popover";
+export * from "./rel-popover-content";

package/dist/components/rel-popover/rel-popover-content.ts

@@ -0,0 +1,55 @@
+import { LitElement, html, css } from "lit";
+import { customElement, property } from "lit/decorators.js";
+
+@customElement("rel-popover-content")
+export class RelPopoverContent extends LitElement {
+  @property({ type: String, attribute: "aria-label" }) ariaLabel = "";
+
+  static styles = css`
+    :host {
+      display: block;
+      width: 100%;
+      max-width: 400px;
+    }
+
+    .popover-content {
+      background: var(--rel-colors-white);
+      border: var(--rel-borders-width-stroke-100) solid var(--rel-colors-gray-border);
+      border-radius: var(--rel-borders-radius-border-radius-200);
+      box-shadow: var(--rel-shadows-shadow-300);
+      padding: var(--rel-spacing-space-md);
+      font-family: var(--rel-fontFamilies-primary);
+      font-size: var(--rel-fontSizes-sm);
+      color: var(--rel-colors-gray-heading);
+    }
+
+    .popover-content ::slotted(h1),
+    .popover-content ::slotted(h2),
+    .popover-content ::slotted(h3),
+    .popover-content ::slotted(h4),
+    .popover-content ::slotted(h5),
+    .popover-content ::slotted(h6) {
+      margin: 0 0 var(--rel-spacing-space-xs);
+      font-weight: var(--rel-fontWeights-semibold);
+      color: var(--rel-colors-gray-heading);
+    }
+
+    .popover-content ::slotted(p) {
+      margin: 0 0 var(--rel-spacing-space-sm);
+      color: var(--rel-colors-gray-placeholder);
+      line-height: var(--rel-lineHeights-md);
+    }
+
+    .popover-content ::slotted(p:last-child) {
+      margin-bottom: 0;
+    }
+  `;
+
+  render() {
+    return html`
+      <div class="popover-content" part="content" role="dialog" aria-label="${this.ariaLabel}">
+        <slot></slot>
+      </div>
+    `;
+  }
+}