@reliability-design/web 1.0.2 → 1.0.6

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

@@ -0,0 +1,151 @@
+# rel-kbd
+
+A keyboard key/shortcut pill component for displaying keyboard shortcuts and key combinations in a visually consistent way.
+
+## Usage
+
+```html
+<!-- Basic usage -->
+<rel-kbd>K</rel-kbd>
+
+<!-- Keyboard shortcut combination -->
+<rel-kbd>Ctrl</rel-kbd> + <rel-kbd>K</rel-kbd>
+
+<!-- With variants -->
+<rel-kbd variant="muted">⌘</rel-kbd>
+<rel-kbd variant="default">Shift</rel-kbd>
+
+<!-- Different sizes -->
+<rel-kbd size="sm">Esc</rel-kbd>
+<rel-kbd size="md">Enter</rel-kbd>
+<rel-kbd size="lg">Space</rel-kbd>
+
+<!-- Pill shape -->
+<rel-kbd pill>R</rel-kbd>
+
+<!-- Inset (pressed) appearance -->
+<rel-kbd inset>Tab</rel-kbd>
+```
+
+## API
+
+### Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Controls the size of the kbd element |
+| `variant` | `"default" \| "muted"` | `"default"` | Visual style variant |
+| `pill` | `boolean` | `false` | When true, renders with full rounded corners |
+| `inset` | `boolean` | `false` | When true, renders with pressed/inset appearance |
+
+### Slots
+
+| Slot | Description |
+|------|-------------|
+| (default) | The keyboard key label or character |
+
+### CSS Custom Properties
+
+The component uses design tokens from the Reliability Design System:
+
+#### Colors
+- `--rel-colors-gray-light` - Default background
+- `--rel-colors-gray-background` - Muted and inset backgrounds
+- `--rel-colors-gray-heading` - Default text color
+- `--rel-colors-gray-placeholder` - Muted text color
+- `--rel-colors-gray-border` - Default border
+- `--rel-colors-gray-divider` - Muted border
+
+#### Typography
+- `--rel-fontFamilies-primary` - Font family (Poppins)
+- `--rel-fontWeights-medium` - Font weight (500)
+- `--rel-fontSizes-xs` - Small size font
+- `--rel-fontSizes-sm` - Medium size font
+- `--rel-fontSizes-md` - Large size font
+
+#### Spacing
+- `--rel-spacing-space-3xs` (2px)
+- `--rel-spacing-space-2xs` (4px)
+- `--rel-spacing-space-xs` (8px)
+- `--rel-spacing-space-sm` (12px)
+- `--rel-spacing-space-md` (16px)
+
+#### Borders
+- `--rel-borders-width-stroke-100` (1px)
+- `--rel-borders-radius-border-radius-100` (2px)
+- `--rel-borders-radius-border-radius-200` (8px)
+- `--rel-borders-radius-border-radius-500` (1000px - pill shape)
+
+## Examples
+
+### Search Shortcut
+```html
+<p>Press <rel-kbd>Ctrl</rel-kbd> + <rel-kbd>K</rel-kbd> to search</p>
+```
+
+### Mac Shortcut
+```html
+<p>Press <rel-kbd variant="muted">⌘</rel-kbd> + <rel-kbd>Shift</rel-kbd> + <rel-kbd pill>R</rel-kbd> to reload</p>
+```
+
+### Multiple Sizes
+```html
+<div style="display: flex; gap: 8px; align-items: center;">
+  <rel-kbd size="sm">S</rel-kbd>
+  <rel-kbd size="md">M</rel-kbd>
+  <rel-kbd size="lg">L</rel-kbd>
+</div>
+```
+
+### Pressed State
+```html
+<p>Hold <rel-kbd inset>Space</rel-kbd> to preview</p>
+```
+
+## Accessibility
+
+- Uses semantic `<kbd>` HTML element for proper semantics
+- `role="presentation"` is set to avoid redundant announcements
+- Non-interactive by default (no tabindex)
+- Text content is fully accessible to screen readers
+- Inherits text color that maintains sufficient contrast ratios
+
+## Styling Notes
+
+### Default Appearance
+- Subtle background with light border
+- Small inset highlight shadow for raised appearance
+- Monospaced font weight for technical look
+
+### Muted Variant
+- Lower contrast for secondary shortcuts
+- Softer colors and reduced shadow
+
+### Pill Modifier
+- Fully rounded corners using border-radius-500 token
+- Ideal for single character keys
+
+### Inset Modifier
+- Inverted shadow for pressed/active appearance
+- Slight vertical translation for depth effect
+- Darker background to indicate pressed state
+
+## Dark Mode Support
+
+The component automatically supports dark mode when design tokens are configured with dark mode variants, as it exclusively uses CSS custom properties.
+
+## Browser Support
+
+Compatible with all modern browsers that support:
+- Web Components
+- CSS Custom Properties
+- Shadow DOM
+
+## Framework Integration
+
+Works seamlessly with:
+- Vanilla JavaScript
+- Angular
+- React (via wrapper)
+- Vue
+- Any framework that supports Web Components

package/dist/components/rel-kbd/rel-kbd.ts

@@ -0,0 +1,118 @@
+import { LitElement, html, css } from "lit";
+import { customElement, property } from "lit/decorators.js";
+
+@customElement("rel-kbd")
+export class RelKbd extends LitElement {
+  @property({ type: String, reflect: true })
+  size: "sm" | "md" | "lg" = "md";
+
+  @property({ type: String, reflect: true })
+  variant: "default" | "muted" = "default";
+
+  @property({ type: Boolean, reflect: true })
+  pill = false;
+
+  @property({ type: Boolean, reflect: true })
+  inset = false;
+
+  static styles = css`
+    :host {
+      display: inline-flex;
+    }
+
+    kbd {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      font-family: var(--rel-fontFamilies-primary);
+      font-weight: var(--rel-fontWeights-medium);
+      white-space: nowrap;
+      user-select: none;
+      transition: all 0.15s ease;
+      line-height: 1;
+      vertical-align: middle;
+    }
+
+    /* Size variants */
+    .kbd-sm {
+      font-size: var(--rel-fontSizes-xs);
+      padding: var(--rel-spacing-space-3xs) var(--rel-spacing-space-xs);
+      min-width: 20px;
+      height: 20px;
+      border-radius: var(--rel-borders-radius-border-radius-100);
+    }
+
+    .kbd-md {
+      font-size: var(--rel-fontSizes-sm);
+      padding: var(--rel-spacing-space-2xs) var(--rel-spacing-space-sm);
+      min-width: 24px;
+      height: 24px;
+      border-radius: var(--rel-borders-radius-border-radius-100);
+    }
+
+    .kbd-lg {
+      font-size: var(--rel-fontSizes-md);
+      padding: var(--rel-spacing-space-xs) var(--rel-spacing-space-md);
+      min-width: 32px;
+      height: 32px;
+      border-radius: var(--rel-borders-radius-border-radius-200);
+    }
+
+    /* Variant: default */
+    .kbd-default {
+      background: var(--rel-colors-gray-light);
+      color: var(--rel-colors-gray-heading);
+      border: var(--rel-borders-width-stroke-100) solid var(--rel-colors-gray-border);
+      box-shadow: 0 1px 2px rgba(0, 0, 0, 0.05), 0 1px 0 0 rgba(255, 255, 255, 0.5) inset;
+    }
+
+    /* Variant: muted */
+    .kbd-muted {
+      background: var(--rel-surface-secondary, #fafafa);
+      color: var(--rel-colors-gray-placeholder);
+      border: var(--rel-borders-width-stroke-100) solid var(--rel-colors-gray-divider);
+      box-shadow: 0 1px 1px rgba(0, 0, 0, 0.03);
+    }
+
+    /* Pill modifier */
+    :host([pill]) .kbd-sm {
+      border-radius: var(--rel-borders-radius-border-radius-500);
+    }
+
+    :host([pill]) .kbd-md {
+      border-radius: var(--rel-borders-radius-border-radius-500);
+    }
+
+    :host([pill]) .kbd-lg {
+      border-radius: var(--rel-borders-radius-border-radius-500);
+    }
+
+    /* Inset modifier - pressed appearance */
+    :host([inset]) kbd {
+      box-shadow: 0 1px 2px rgba(0, 0, 0, 0.1) inset, 0 1px 0 0 rgba(0, 0, 0, 0.05);
+      transform: translateY(1px);
+    }
+
+    :host([inset]) .kbd-default {
+      background: var(--rel-surface-secondary, #fafafa);
+      border-color: var(--rel-colors-gray-divider);
+    }
+
+    :host([inset]) .kbd-muted {
+      background: var(--rel-colors-gray-divider);
+      border-color: var(--rel-colors-gray-border);
+    }
+  `;
+
+  private get classes() {
+    return ["kbd", `kbd-${this.size}`, `kbd-${this.variant}`].join(" ");
+  }
+
+  render() {
+    return html`
+      <kbd class="${this.classes}" role="presentation">
+        <slot></slot>
+      </kbd>
+    `;
+  }
+}

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

@@ -0,0 +1,88 @@
+# rel-layout
+
+## Overview
+A responsive CSS Grid layout component with automatic breakpoint handling. Provides a configurable grid with customizable column count and gap, automatically adapting to smaller viewports when `responsive` is enabled.
+
+## Usage
+```html
+<!-- Basic 4-column grid -->
+<rel-layout>
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+  <div>Item 4</div>
+  <div>Item 5</div>
+  <div>Item 6</div>
+</rel-layout>
+
+<!-- Custom columns and gap -->
+<rel-layout columns="3" gap="24px">
+  <div>Column 1</div>
+  <div>Column 2</div>
+  <div>Column 3</div>
+</rel-layout>
+
+<!-- Fixed layout (non-responsive) -->
+<rel-layout columns="2" gap="16px" responsive="false">
+  <div>Always 2 columns</div>
+  <div>Even on mobile</div>
+</rel-layout>
+
+<!-- Large gap with 6 columns -->
+<rel-layout columns="6" gap="2rem">
+  <div>Item 1</div>
+  <div>Item 2</div>
+  <div>Item 3</div>
+  <div>Item 4</div>
+  <div>Item 5</div>
+  <div>Item 6</div>
+</rel-layout>
+```
+
+## API
+
+### Attributes/Properties
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `columns` | `number` | `4` | Number of columns in the grid |
+| `gap` | `string` | `"1rem"` | CSS gap value (supports any CSS length unit) |
+| `responsive` (reflected) | `boolean` | `true` | Enable automatic responsive breakpoints |
+
+## Events
+None.
+
+## Slots
+| Slot | Description |
+|------|-------------|
+| (default) | Grid items (any HTML elements) |
+
+## CSS Parts
+None exposed.
+
+## Tokens / CSS Variables
+
+### Semantic Tokens
+- `--rel-fontFamilies-primary` - Font family
+
+## Accessibility
+- Uses standard CSS Grid, which is accessible by default
+- Ensure grid items contain proper semantic HTML
+
+### Keyboard Interactions
+- Standard browser navigation through grid items
+
+### Focus Behavior
+- No specific focus handling (relies on slotted content)
+
+## Notes / Edge Cases
+- **Responsive breakpoints** (only when `responsive` is true):
+  - **≤1024px**: 3 columns
+  - **≤768px**: 2 columns
+  - **≤480px**: 1 column
+- The `responsive` attribute is reflected, so CSS can target `:host([responsive])`
+- Responsive styles use `!important` to override inline column count
+- If `responsive` is set to `false`, the grid maintains the specified column count at all viewport sizes
+- The grid is `display: grid` with `width: 100%`
+- The `columns` and `gap` properties are applied as inline styles for maximum flexibility
+- The component is `display: block` and `width: 100%`
+- Grid items do not have any default styling—you must style them yourself

package/dist/components/rel-layout/rel-layout.ts

@@ -3,11 +3,12 @@ import { customElement, property } from "lit/decorators.js";
 
 @customElement("rel-layout")
 export class RelLayout extends LitElement {
-  @property({ type: String }) gap: string = "1rem";
+  @property({ type: String }) gap = "1rem";
 
-  @property({ type: Number }) columns: number = 4;
+  @property({ type: Number }) columns = 4;
 
-  @property({ type: Boolean }) responsive: boolean = true;
+  // 🔥 IMPORTANT: reflect so CSS selectors work
+  @property({ type: Boolean, reflect: true }) responsive = true;
 
   static styles = css`
     :host {
@@ -21,11 +22,7 @@ export class RelLayout extends LitElement {
       font-family: var(--rel-fontFamilies-primary);
     }
 
-    /* Responsive breakpoints - only applied when responsive is true */
-    :host([responsive]) .layout-grid {
-      /* Default: use columns property */
-    }
-
+    /* Responsive breakpoints — only when attribute exists */
     @media (max-width: 1024px) {
       :host([responsive]) .layout-grid {
         grid-template-columns: repeat(3, 1fr) !important;
@@ -46,13 +43,14 @@ export class RelLayout extends LitElement {
   `;
 
   render() {
-    const gridStyle = `
-      gap: ${this.gap};
-      grid-template-columns: repeat(${this.columns}, 1fr);
-    `;
-
     return html`
-      <div class="layout-grid" style="${gridStyle}">
+      <div
+        class="layout-grid"
+        style="
+          gap: ${this.gap};
+          grid-template-columns: repeat(${this.columns}, 1fr);
+        "
+      >
         <slot></slot>
       </div>
     `;

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

@@ -0,0 +1,151 @@
+# rel-menu
+
+## Overview
+A rich menu component supporting three modes: default (selectable items), checkbox (multi-select), and arrow (nested submenus). Features keyboard navigation, focus management, disabled items, active states, and automatic submenu positioning.
+
+## Usage
+```html
+<!-- Default menu (single selection) -->
+<rel-menu id="defaultMenu" type="default"></rel-menu>
+<script>
+  const menu = document.getElementById('defaultMenu');
+  menu.items = [
+    { label: 'Edit', active: false },
+    { label: 'Copy', active: true },
+    { label: 'Paste', active: false },
+    { label: 'Delete', disabled: true }
+  ];
+  menu.addEventListener('item-selected', (e) => {
+    console.log('Selected:', e.detail.item.label);
+  });
+</script>
+
+<!-- Checkbox menu (multi-select) -->
+<rel-menu id="checkMenu" type="checkbox"></rel-menu>
+<script>
+  const checkMenu = document.getElementById('checkMenu');
+  checkMenu.items = [
+    { label: 'Show Grid', checked: true },
+    { label: 'Show Rulers', checked: false },
+    { label: 'Show Guides', checked: true }
+  ];
+  checkMenu.addEventListener('item-checked', (e) => {
+    console.log(e.detail.item.label, 'is', e.detail.checked ? 'checked' : 'unchecked');
+  });
+</script>
+
+<!-- Arrow menu (nested submenus) -->
+<rel-menu id="arrowMenu" type="arrow"></rel-menu>
+<script>
+  const arrowMenu = document.getElementById('arrowMenu');
+  arrowMenu.items = [
+    { label: 'File', submenu: [
+      { label: 'New' },
+      { label: 'Open' },
+      { label: 'Save', disabled: false }
+    ]},
+    { label: 'Edit', submenu: [
+      { label: 'Undo' },
+      { label: 'Redo' }
+    ]},
+    { label: 'Help' }
+  ];
+  arrowMenu.addEventListener('submenu-selected', (e) => {
+    console.log('Submenu item:', e.detail.sub.label, 'from', e.detail.parent.label);
+  });
+</script>
+```
+
+## API
+
+### Attributes/Properties
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `"default" \| "checkbox" \| "arrow"` | `"default"` | Menu behavior mode |
+| `items` | `MenuItem[]` | `[]` | Array of menu items (see MenuItem interface below) |
+
+### MenuItem Interface
+```typescript
+interface MenuItem {
+  label: string;           // Display text
+  active?: boolean;        // Highlighted/selected state (default/arrow modes)
+  checked?: boolean;       // Checkbox state (checkbox mode)
+  disabled?: boolean;      // Disables interaction
+  submenu?: MenuItem[];    // Nested menu items (arrow mode)
+  open?: boolean;          // Submenu visibility state (arrow mode)
+}
+```
+
+## Events
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `item-selected` | `{ item: MenuItem }` | Fired when an item is selected (default mode) |
+| `item-checked` | `{ item: MenuItem, checked: boolean }` | Fired when a checkbox item is toggled (checkbox mode) |
+| `submenu-selected` | `{ parent: MenuItem, sub: MenuItem }` | Fired when a submenu item is selected (arrow mode) |
+
+## Slots
+Default slot not used.
+
+## CSS Parts
+None exposed.
+
+## Tokens / CSS Variables
+
+### Semantic Tokens
+- `--rel-fontFamilies-primary` - Font family
+- `--rel-fontSizes-sm` - Font size
+- `--rel-fontSizes-lg` - Chevron font size
+- `--rel-fontWeights-medium` - Active item font weight
+- `--rel-lineHeights-sm` - Line height
+
+### Spacing Tokens
+- `--rel-spacing-space-3xs` - Menu vertical padding
+- `--rel-spacing-space-xs` - Item padding, gaps
+- `--rel-spacing-space-sm` - Item horizontal padding
+- `--rel-spacing-space-2xs` - Checkbox gap, submenu offset
+
+### Color Tokens
+- `--rel-colors-white` - Menu and submenu background
+- `--rel-text-primary` - Default text color
+- `--rel-text-disabled` - Disabled item text
+- `--rel-surface-secondary` - Hover and active background
+- `--rel-colors-gray-divider` - Active press background
+- `--rel-colors-blue-primary` - Focus outline
+
+### Shadow Tokens
+- `--rel-shadows-shadow-300` - Menu and submenu drop shadow
+
+### Border Tokens
+- `--rel-borders-radius-border-radius-300` - Border radius
+
+## Accessibility
+- Uses `role="menu"` on container and `role="menuitem"` on items
+- Keyboard navigation with Arrow keys, Enter, Space, and Escape
+- Focus visible states with blue outline on menu and items
+- Disabled items have reduced color and are non-interactive
+- Close submenu when clicking outside the menu
+
+### Keyboard Interactions
+- `Arrow Down` - Move focus to next item
+- `Arrow Up` - Move focus to previous item
+- `Arrow Right` - Open focused submenu (arrow mode)
+- `Arrow Left / Escape` - Close all submenus
+- `Enter / Space` - Activate focused item
+- `Tab` - Focus menu container
+
+### Focus Behavior
+- Menu container receives focus on Tab
+- Focused items show blue outline with -2px offset (inside boundary)
+- Focus index tracked programmatically for keyboard navigation
+
+## Notes / Edge Cases
+- **Default mode**: Clicking an item sets `active: true` on that item and `active: false` on all others
+- **Checkbox mode**: Clicking toggles the `checked` state; also clicking the checkbox input itself triggers the same event
+- **Arrow mode**: Submenus open on hover (`mouseenter`) and clicking toggles them; clicking a submenu item closes the submenu
+- Submenus are positioned absolutely at `left: 100%` and `top: -<padding>` relative to parent item
+- Clicking outside the menu (document-level listener) closes all open submenus
+- Disabled items cannot be activated, checked, or expanded
+- In arrow mode, only one submenu can be open at a time (opening one closes others)
+- The menu has a minimum width of `220px`, submenus have `200px`
+- Chevron (▸) appears only on items with `submenu` in arrow mode
+- Native checkbox inputs are used in checkbox mode (16px × 16px)

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

@@ -28,16 +28,22 @@ export class RelMenu extends LitElement {
     .rel-menu {
       position: relative;
       display: inline-block;
-      background: var(--rel-colors-white);
+      background: var(--rel-colors-white, #fff);
+      color: var(--rel-text-primary, #333);
       border-radius: var(--rel-borders-radius-border-radius-300);
       box-shadow: var(--rel-shadows-shadow-300);
       min-width: 220px;
-      font-family: var(--rel-fontFamilies-primary);
+      font-family: var(--rel-fontFamilies-primary, sans-serif);
       font-size: var(--rel-fontSizes-sm);
       padding: var(--rel-spacing-space-3xs) 0;
       outline: none;
     }
 
+    .rel-menu:focus-visible {
+      outline: 2px solid var(--rel-colors-blue-primary, #0091ea);
+      outline-offset: 2px;
+    }
+
     .rel-menu-item {
       position: relative;
       display: flex;
@@ -51,26 +57,27 @@ export class RelMenu extends LitElement {
     }
 
     .rel-menu-item:hover {
-      background: var(--rel-colors-gray-border);
+      background: var(--rel-surface-secondary, #fafafa);
     }
 
     .rel-menu-item:active {
-      background: var(--rel-colors-gray-tertiary);
+      background: var(--rel-colors-gray-divider, #bdbdbd);
     }
 
     .rel-menu-item.active {
-      background: var(--rel-colors-gray-tertiary);
+      background: var(--rel-surface-secondary, #fafafa);
+      font-weight: var(--rel-fontWeights-medium);
     }
 
     .rel-menu-item.disabled {
-      background-color: var(--rel-colors-gray-light);
-      color: var(--rel-colors-gray-placeholder);
+      background-color: transparent;
+      color: var(--rel-text-disabled, #9e9e9e);
       cursor: not-allowed;
     }
 
     .rel-menu-item[data-focused="true"] {
-      border-top: var(--rel-borders-width-stroke-200) solid var(--rel-colors-gray-primary);
-      border-bottom: var(--rel-borders-width-stroke-200) solid var(--rel-colors-gray-primary);
+      outline: 2px solid var(--rel-colors-blue-primary, #0091ea);
+      outline-offset: -2px;
     }
 
     .menu-check-row {
@@ -105,7 +112,8 @@ export class RelMenu extends LitElement {
       top: calc(-1 * var(--rel-spacing-space-3xs));
       left: calc(100% + var(--rel-spacing-space-2xs));
       min-width: 200px;
-      background: var(--rel-colors-white);
+      background: var(--rel-colors-white, #fff);
+      color: var(--rel-text-primary, #333);
       border-radius: var(--rel-borders-radius-border-radius-300);
       box-shadow: var(--rel-shadows-shadow-300);
       padding: var(--rel-spacing-space-3xs) 0;