@reliability-design/web 1.0.3 → 1.0.6

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,143 @@
+import { LitElement, html, css } from "lit";
+import { customElement, property, state } 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 = "";
+
+  @state() private hasContent = 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;
+    }
+
+    .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;
+    }
+
+    .content {
+      display: none;
+    }
+  `;
+
+  connectedCallback() {
+    super.connectedCallback();
+    // Generate item-id from label if not provided
+    if (!this.itemId && this.label) {
+      this.itemId = this.label.toLowerCase().replace(/\s+/g, "-");
+    }
+  }
+
+  firstUpdated() {
+    // Check if there's any slotted content
+    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() {
+    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()
+      );
+    }
+  }
+
+  get triggerId() {
+    return `nav-trigger-${this.itemId}`;
+  }
+
+  get panelId() {
+    return `nav-panel-${this.itemId}`;
+  }
+
+  render() {
+    const isLink = !!this.href && !this.hasContent;
+    const tagName = isLink ? "a" : "button";
+    const attrs = isLink
+      ? { href: this.href }
+      : {
+          type: "button",
+          "aria-haspopup": this.hasContent ? "menu" : undefined,
+          "aria-controls": this.hasContent ? this.panelId : undefined,
+        };
+
+    return html`
+      ${isLink
+        ? html`
+            <a
+              class="trigger"
+              href="${this.href}"
+              id="${this.triggerId}"
+              ?disabled="${this.disabled}"
+            >
+              ${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 : ""}"
+            >
+              ${this.label}
+            </button>
+          `}
+      <div class="content">
+        <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>
+    `;
+  }
+}