@reliability-design/web 1.0.3 → 1.1.1

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-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)