@reliability-design/web 1.0.3 → 1.1.1

package/dist/components/rel-nav-menu/README.md

@@ -0,0 +1,289 @@
+# rel-nav-menu
+
+A horizontal navigation menu component with dropdown panels, perfect for top-level site navigation. Features keyboard navigation, accessible ARIA attributes, and token-driven styling.
+
+## What It Is
+
+The navigation menu consists of three custom elements:
+- `<rel-nav-menu>` - Root container that manages navigation state and interactions
+- `<rel-nav-menu-item>` - Individual navigation items (can be links or dropdown triggers)
+- `<rel-nav-menu-panel>` - Styled container for dropdown content
+
+## Basic Usage
+
+```html
+<rel-nav-menu>
+  <rel-nav-menu-item label="Features" href="#features"></rel-nav-menu-item>
+  <rel-nav-menu-item label="Pricing" href="#pricing"></rel-nav-menu-item>
+  <rel-nav-menu-item label="About" href="#about"></rel-nav-menu-item>
+  <rel-nav-menu-item label="Contact" href="#contact"></rel-nav-menu-item>
+</rel-nav-menu>
+```
+
+## Dropdown with Content
+
+```html
+<rel-nav-menu>
+  <rel-nav-menu-item label="Getting started">
+    <rel-nav-menu-panel>
+      <a href="#intro" data-nav-item>
+        <div data-title>Introduction</div>
+        <div data-desc>Re-usable components built with Tailwind CSS.</div>
+      </a>
+      <a href="#install" data-nav-item>
+        <div data-title>Installation</div>
+        <div data-desc>How to install dependencies and structure your app.</div>
+      </a>
+      <a href="#typography" data-nav-item>
+        <div data-title>Typography</div>
+        <div data-desc>Styles for headings, paragraphs, lists...</div>
+      </a>
+    </rel-nav-menu-panel>
+  </rel-nav-menu-item>
+
+  <rel-nav-menu-item label="Components">
+    <rel-nav-menu-panel>
+      <a href="#accordion" data-nav-item>
+        <div data-title>Accordion</div>
+        <div data-desc>Vertically stacked interactive headings.</div>
+      </a>
+      <a href="#alert" data-nav-item>
+        <div data-title>Alert Dialog</div>
+        <div data-desc>Modal dialog that interrupts the user.</div>
+      </a>
+    </rel-nav-menu-panel>
+  </rel-nav-menu-item>
+
+  <rel-nav-menu-item label="Docs" href="#docs"></rel-nav-menu-item>
+</rel-nav-menu>
+```
+
+## Simple Dropdown List
+
+For simpler dropdowns without titles and descriptions:
+
+```html
+<rel-nav-menu>
+  <rel-nav-menu-item label="Status">
+    <rel-nav-menu-panel>
+      <a href="#backlog" data-nav-item>Backlog</a>
+      <a href="#todo" data-nav-item>To Do</a>
+      <a href="#in-progress" data-nav-item>In Progress</a>
+      <a href="#done" data-nav-item>Done</a>
+    </rel-nav-menu-panel>
+  </rel-nav-menu-item>
+</rel-nav-menu>
+```
+
+## API Reference
+
+### rel-nav-menu
+
+Root navigation container.
+
+**Attributes:**
+- `open` (string) - ID of currently open item (reflects to attribute)
+- `disabled` (boolean) - Disables all interactions
+- `density` ("comfortable" | "compact") - Spacing density, default: "comfortable"
+
+**Events:**
+- `rel-nav-open-change` - Emitted when open state changes
+  ```typescript
+  detail: { openId: string }
+  ```
+
+**Example:**
+```javascript
+const navMenu = document.querySelector('rel-nav-menu');
+navMenu.addEventListener('rel-nav-open-change', (e) => {
+  console.log('Open item:', e.detail.openId);
+});
+```
+
+### rel-nav-menu-item
+
+Individual navigation item (link or dropdown trigger).
+
+**Attributes:**
+- `label` (string, required) - Text displayed on the trigger
+- `href` (string, optional) - If provided, renders as link (no dropdown)
+- `item-id` (string, optional) - Stable identifier; auto-generated from label if not provided
+- `disabled` (boolean) - Disables this item
+- `icon` (string, optional) - Reserved for future icon support
+
+**Behavior:**
+- If `href` is set and no dropdown content → renders as anchor link
+- If dropdown content exists → renders as button with dropdown
+- Auto-generates `item-id` from label if not specified
+
+**Slots:**
+- Default slot: dropdown panel content (if any)
+
+### rel-nav-menu-panel
+
+Styled container for dropdown content.
+
+**Usage:**
+Place inside `<rel-nav-menu-item>` to create dropdown content.
+
+**Content Structure:**
+Use data attributes for styling:
+- `data-nav-item` - On anchor/link elements for hover styling
+- `data-title` - For the main title text
+- `data-desc` - For the description text
+
+## Keyboard Navigation
+
+Full keyboard accessibility support:
+
+| Key | Action |
+|-----|--------|
+| `Tab` / `Shift+Tab` | Navigate through triggers |
+| `ArrowLeft` | Move focus to previous trigger |
+| `ArrowRight` | Move focus to next trigger |
+| `Enter` / `Space` | Open/close focused dropdown (if it has content) |
+| `ArrowDown` | Move focus into open dropdown panel (first focusable element) |
+| `Escape` | Close open dropdown and return focus to trigger |
+
+## Interaction Behavior
+
+### Mouse Interactions
+- **Click** a trigger to toggle its dropdown
+- **Click** another trigger to switch dropdowns
+- **Click outside** to close dropdown
+- **Hover switching**: When a dropdown is open, hovering another trigger switches to it
+
+### Accessibility
+- Root has `role="navigation"`
+- Dropdown triggers have `aria-haspopup="menu"`, `aria-expanded`, and `aria-controls`
+- Panels have matching `id` attributes
+- Disabled items are marked with `aria-disabled`
+- Focus management with visible focus indicators
+
+## Styling Tokens
+
+The component uses design tokens from the Reliability Design System:
+
+### Colors
+- `--rel-colors-gray-light` - Nav container background
+- `--rel-colors-gray-background` - Trigger hover/active state, panel item hover
+- `--rel-colors-gray-border` - Borders
+- `--rel-colors-gray-heading` - Text color
+- `--rel-colors-gray-placeholder` - Description text
+- `--rel-colors-white` - Panel background
+- `--rel-colors-blue-primary` - Focus outline
+
+### Typography
+- `--rel-fontFamilies-primary` - Font family (Poppins)
+- `--rel-fontWeights-medium` - Trigger text weight
+- `--rel-fontWeights-semibold` - Panel item title weight
+- `--rel-fontSizes-sm` - Trigger and title text size
+- `--rel-fontSizes-xs` - Description text size
+- `--rel-lineHeights-xs` - Description line height
+
+### Spacing
+- `--rel-spacing-space-3xs` (2px) - Compact spacing
+- `--rel-spacing-space-2xs` (4px) - Container padding, panel gaps
+- `--rel-spacing-space-xs` (8px) - Trigger padding, panel padding
+- `--rel-spacing-space-sm` (12px) - Panel item padding
+- `--rel-spacing-space-md` (16px) - Trigger horizontal padding
+
+### Borders & Effects
+- `--rel-borders-width-stroke-100` (1px) - Border width
+- `--rel-borders-radius-border-radius-100` (2px) - Panel item radius
+- `--rel-borders-radius-border-radius-200` (8px) - Container and panel radius
+- `--rel-shadows-shadow-300` - Panel drop shadow
+
+### Z-Index
+- Dropdown panels: `z-index: 1000`
+
+## Positioning
+
+Dropdown panels use fixed positioning with smart collision detection:
+- **Default**: Opens below trigger, start-aligned
+- **Right overflow**: Shifts left to fit viewport
+- **Bottom overflow**: Flips above trigger if more space available
+
+## Complete Example
+
+```html
+<rel-nav-menu id="main-nav">
+  <rel-nav-menu-item label="Getting started">
+    <rel-nav-menu-panel>
+      <a href="#intro" data-nav-item>
+        <div data-title>Introduction</div>
+        <div data-desc>Re-usable components built using Radix UI and Tailwind CSS.</div>
+      </a>
+      <a href="#installation" data-nav-item>
+        <div data-title>Installation</div>
+        <div data-desc>How to install dependencies and structure your app.</div>
+      </a>
+      <a href="#typography" data-nav-item>
+        <div data-title>Typography</div>
+        <div data-desc>Styles for headings, paragraphs, lists, and more.</div>
+      </a>
+    </rel-nav-menu-panel>
+  </rel-nav-menu-item>
+
+  <rel-nav-menu-item label="Components">
+    <rel-nav-menu-panel>
+      <a href="#accordion" data-nav-item>
+        <div data-title>Accordion</div>
+        <div data-desc>A vertically stacked set of interactive headings.</div>
+      </a>
+      <a href="#alert-dialog" data-nav-item>
+        <div data-title>Alert Dialog</div>
+        <div data-desc>A modal dialog that interrupts the user.</div>
+      </a>
+      <a href="#avatar" data-nav-item>
+        <div data-title>Avatar</div>
+        <div data-desc>An image element with a fallback.</div>
+      </a>
+    </rel-nav-menu-panel>
+  </rel-nav-menu-item>
+
+  <rel-nav-menu-item label="Status">
+    <rel-nav-menu-panel>
+      <a href="#backlog" data-nav-item>Backlog</a>
+      <a href="#todo" data-nav-item>To Do</a>
+      <a href="#in-progress" data-nav-item>In Progress</a>
+      <a href="#done" data-nav-item>Done</a>
+    </rel-nav-menu-panel>
+  </rel-nav-menu-item>
+
+  <rel-nav-menu-item label="Documentation" href="#docs"></rel-nav-menu-item>
+</rel-nav-menu>
+
+<script>
+  const navMenu = document.getElementById('main-nav');
+  navMenu.addEventListener('rel-nav-open-change', (e) => {
+    console.log('Navigation state:', e.detail.openId);
+  });
+</script>
+```
+
+## Browser Support
+
+Compatible with all modern browsers supporting:
+- Web Components (Custom Elements v1)
+- Shadow DOM
+- ES2020+ features
+
+## Framework Integration
+
+Works seamlessly with:
+- Vanilla JavaScript
+- Angular
+- React (via wrapper)
+- Vue
+- Any framework supporting Web Components
+
+## Comparison with Menubar
+
+While `rel-menubar` is designed for application menus (File/Edit/View), `rel-nav-menu` is optimized for:
+- **Website navigation** - Top-level site sections
+- **Content-rich dropdowns** - With titles, descriptions, and icons
+- **Flexible layouts** - Horizontal navigation bars
+- **Marketing sites** - Product features, documentation, etc.
+
+Use `rel-menubar` for desktop application UIs, use `rel-nav-menu` for website navigation.

package/dist/components/rel-nav-menu/index.ts

@@ -0,0 +1,3 @@
+export * from "./rel-nav-menu";
+export * from "./rel-nav-menu-item";
+export * from "./rel-nav-menu-panel";

package/dist/components/rel-nav-menu/rel-nav-menu-item.ts

@@ -0,0 +1,240 @@
+import { LitElement, html, css } from "lit";
+import { customElement, property } from "lit/decorators.js";
+
+@customElement("rel-nav-menu-item")
+export class RelNavMenuItem extends LitElement {
+  @property({ type: String }) label = "";
+  @property({ type: String }) href = "";
+  @property({ type: String, attribute: "item-id" }) itemId = "";
+  @property({ type: Boolean, reflect: true }) disabled = false;
+  @property({ type: String }) icon = "";
+
+  /** Promoted from @state so rel-nav-menu can read it as a property. */
+  @property({ type: Boolean, reflect: true }) hasContent = false;
+
+  /** Set by rel-nav-menu to open/close this item's panel. */
+  @property({ type: Boolean, reflect: true }) open = false;
+
+  static styles = css`
+    :host {
+      display: inline-block;
+    }
+
+    .trigger {
+      display: inline-flex;
+      align-items: center;
+      gap: var(--rel-spacing-space-2xs);
+      padding: var(--rel-spacing-space-xs) var(--rel-spacing-space-md);
+      font-family: var(--rel-fontFamilies-primary);
+      font-size: var(--rel-fontSizes-sm);
+      font-weight: var(--rel-fontWeights-medium);
+      color: var(--rel-colors-gray-heading);
+      background: transparent;
+      border: none;
+      border-radius: var(--rel-borders-radius-border-radius-200);
+      cursor: pointer;
+      transition: all 0.15s ease;
+      text-decoration: none;
+      outline: none;
+      user-select: none;
+    }
+
+    .trigger:hover:not(:disabled) {
+      background: var(--rel-surface-secondary, #fafafa);
+    }
+
+    .trigger:focus-visible {
+      outline: 2px solid var(--rel-colors-blue-primary);
+      outline-offset: 2px;
+    }
+
+    /* Active state driven by :host([open]) — no external class manipulation needed */
+    :host([open]) .trigger,
+    .trigger.active {
+      background: var(--rel-surface-secondary, #fafafa);
+    }
+
+    .trigger:disabled {
+      opacity: 0.5;
+      cursor: not-allowed;
+    }
+
+    :host([disabled]) .trigger {
+      opacity: 0.5;
+      cursor: not-allowed;
+    }
+
+    /* Panel lives inside the item's own shadow DOM */
+    .panel {
+      position: fixed;
+      min-width: 320px;
+      max-width: 600px;
+      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-xs);
+      z-index: 1000;
+      display: none;
+    }
+
+    .panel.open {
+      display: block;
+    }
+  `;
+
+  connectedCallback() {
+    super.connectedCallback();
+    if (!this.itemId && this.label) {
+      this.itemId = this.label.toLowerCase().replace(/\s+/g, "-");
+    }
+  }
+
+  firstUpdated() {
+    this.updateHasContent();
+  }
+
+  updated(changed: Map<string, any>) {
+    if (changed.has("open") && this.open) {
+      // Wait for paint so the panel has layout dimensions before positioning.
+      this.updateComplete.then(() => this.positionPanel());
+    }
+  }
+
+  // ── Content detection ──────────────────────────────────────────────────────
+
+  private updateHasContent() {
+    const slot = this.shadowRoot?.querySelector("slot");
+    if (slot) {
+      const nodes = slot.assignedNodes({ flatten: true });
+      this.hasContent = nodes.some(
+        (node) => node.nodeType === Node.ELEMENT_NODE || node.textContent?.trim()
+      );
+    }
+  }
+
+  private handleSlotChange() {
+    this.updateHasContent();
+  }
+
+  // ── Panel positioning (moved from rel-nav-menu) ────────────────────────────
+
+  private positionPanel() {
+    const trigger = this.shadowRoot?.querySelector(".trigger") as HTMLElement;
+    const panel = this.shadowRoot?.querySelector(".panel") as HTMLElement;
+    if (!trigger || !panel) return;
+
+    const triggerRect = trigger.getBoundingClientRect();
+    const panelRect = panel.getBoundingClientRect();
+    const viewportWidth = window.innerWidth;
+    const viewportHeight = window.innerHeight;
+
+    let top = triggerRect.bottom + 8;
+    let left = triggerRect.left;
+
+    // Handle right overflow
+    if (left + panelRect.width > viewportWidth) {
+      left = viewportWidth - panelRect.width - 16;
+    }
+
+    // Handle left overflow
+    if (left < 0) left = 16;
+
+    // Handle bottom overflow — flip above if more space
+    if (top + panelRect.height > viewportHeight) {
+      const spaceAbove = triggerRect.top;
+      const spaceBelow = viewportHeight - triggerRect.bottom;
+      if (spaceAbove > spaceBelow && spaceAbove > panelRect.height) {
+        top = triggerRect.top - panelRect.height - 8;
+      }
+    }
+
+    panel.style.top = `${top}px`;
+    panel.style.left = `${left}px`;
+  }
+
+  // ── Events dispatched upward — rel-nav-menu listens via connectedCallback ──
+
+  private handleTriggerClick() {
+    if (this.disabled) return;
+    this.dispatchEvent(
+      new CustomEvent("rel-nav-item-click", {
+        detail: { itemId: this.itemId, hasContent: this.hasContent },
+        bubbles: true,
+        composed: true,
+      })
+    );
+  }
+
+  private handleTriggerMouseEnter() {
+    if (this.disabled) return;
+    this.dispatchEvent(
+      new CustomEvent("rel-nav-item-hover", {
+        detail: { itemId: this.itemId },
+        bubbles: true,
+        composed: true,
+      })
+    );
+  }
+
+  // ── ID helpers ─────────────────────────────────────────────────────────────
+
+  get triggerId() {
+    return `nav-trigger-${this.itemId}`;
+  }
+
+  get panelId() {
+    return `nav-panel-${this.itemId}`;
+  }
+
+  // ── Render ─────────────────────────────────────────────────────────────────
+
+  render() {
+    const isLink = !!this.href && !this.hasContent;
+
+    return html`
+      ${isLink
+        ? html`
+            <a
+              class="trigger"
+              href="${this.href}"
+              id="${this.triggerId}"
+              ?disabled="${this.disabled}"
+              @click="${this.handleTriggerClick}"
+              @mouseenter="${this.handleTriggerMouseEnter}"
+            >
+              ${this.label}
+            </a>
+          `
+        : html`
+            <button
+              class="trigger"
+              id="${this.triggerId}"
+              type="button"
+              ?disabled="${this.disabled}"
+              aria-haspopup="${this.hasContent ? "menu" : "false"}"
+              aria-controls="${this.hasContent ? this.panelId : ""}"
+              aria-expanded="${this.open ? "true" : "false"}"
+              @click="${this.handleTriggerClick}"
+              @mouseenter="${this.handleTriggerMouseEnter}"
+            >
+              ${this.label}
+            </button>
+          `}
+
+      <!--
+        Panel rendered inside this shadow root.
+        Slot projects the consumer's light-DOM children directly — no cloning.
+        rel-nav-menu sets item.open = true/false to show/hide.
+      -->
+      <div
+        class="panel ${this.open ? "open" : ""}"
+        id="${this.panelId}"
+        role="menu"
+        @click="${(e: Event) => e.stopPropagation()}"
+      >
+        <slot @slotchange="${this.handleSlotChange}"></slot>
+      </div>
+    `;
+  }
+}

package/dist/components/rel-nav-menu/rel-nav-menu-panel.ts

@@ -0,0 +1,53 @@
+import { LitElement, html, css } from "lit";
+import { customElement } from "lit/decorators.js";
+
+@customElement("rel-nav-menu-panel")
+export class RelNavMenuPanel extends LitElement {
+  static styles = css`
+    :host {
+      display: block;
+      width: 100%;
+    }
+
+    .panel-content {
+      display: flex;
+      flex-direction: column;
+      gap: var(--rel-spacing-space-2xs);
+      padding: var(--rel-spacing-space-xs);
+    }
+
+    ::slotted(a[data-nav-item]) {
+      display: block;
+      padding: var(--rel-spacing-space-sm);
+      border-radius: var(--rel-borders-radius-border-radius-100);
+      transition: background 0.15s ease;
+      text-decoration: none;
+      color: inherit;
+    }
+
+    ::slotted(a[data-nav-item]:hover) {
+      background: var(--rel-surface-secondary, #fafafa);
+    }
+
+    ::slotted([data-title]) {
+      font-size: var(--rel-fontSizes-sm);
+      font-weight: var(--rel-fontWeights-semibold);
+      color: var(--rel-colors-gray-heading);
+      margin-bottom: var(--rel-spacing-space-3xs);
+    }
+
+    ::slotted([data-desc]) {
+      font-size: var(--rel-fontSizes-xs);
+      color: var(--rel-colors-gray-placeholder);
+      line-height: var(--rel-lineHeights-xs);
+    }
+  `;
+
+  render() {
+    return html`
+      <div class="panel-content">
+        <slot></slot>
+      </div>
+    `;
+  }
+}