@reliability-design/web 1.0.3 → 1.0.6

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

@@ -0,0 +1,329 @@
+# rel-menubar
+
+A horizontal menubar component with dropdown menus, submenus, checkbox items, and radio groups. Provides full keyboard navigation and accessibility features.
+
+## What It Is
+
+The menubar component consists of two custom elements:
+- `<rel-menubar>` - The root container that manages state and interactions
+- `<rel-menubar-menu>` - Individual menu definitions with their content
+
+Content is authored using semantic HTML with data attributes, allowing the component to enhance it with proper menubar behavior.
+
+## Basic Usage
+
+```html
+<rel-menubar>
+  <rel-menubar-menu label="File">
+    <button data-item>New Tab</button>
+    <button data-item>New Window</button>
+    <button data-item>Close</button>
+  </rel-menubar-menu>
+
+  <rel-menubar-menu label="Edit">
+    <button data-item>Undo</button>
+    <button data-item>Redo</button>
+    <div data-separator></div>
+    <button data-item>Cut</button>
+    <button data-item>Copy</button>
+    <button data-item>Paste</button>
+  </rel-menubar-menu>
+
+  <rel-menubar-menu label="View">
+    <button data-item>Zoom In</button>
+    <button data-item>Zoom Out</button>
+  </rel-menubar-menu>
+</rel-menubar>
+```
+
+## Submenu Example
+
+Use `data-submenu` attribute with a `label` attribute to create nested menus:
+
+```html
+<rel-menubar>
+  <rel-menubar-menu label="File">
+    <button data-item>New Tab</button>
+    <div data-separator></div>
+    <div data-submenu label="Share">
+      <button data-item>Email link</button>
+      <button data-item>Messages</button>
+      <button data-item>Notes</button>
+    </div>
+    <div data-separator></div>
+    <button data-item>Close</button>
+  </rel-menubar-menu>
+</rel-menubar>
+```
+
+## Checkbox Example
+
+Wrap a checkbox input in a label with `data-checkbox` attribute:
+
+```html
+<rel-menubar>
+  <rel-menubar-menu label="View">
+    <label data-checkbox>
+      <input type="checkbox" />
+      Always Show Bookmarks Bar
+    </label>
+    <label data-checkbox>
+      <input type="checkbox" checked />
+      Always Show Full URLs
+    </label>
+  </rel-menubar-menu>
+</rel-menubar>
+```
+
+## Radio Group Example
+
+Use `data-radio-group` container with `data-radio` items:
+
+```html
+<rel-menubar>
+  <rel-menubar-menu label="Profile">
+    <div data-radio-group name="user-profile" value="andy">
+      <button data-radio value="andy">Andy</button>
+      <button data-radio value="benoit">Benoit</button>
+      <button data-radio value="luis">Luis</button>
+    </div>
+  </rel-menubar-menu>
+</rel-menubar>
+```
+
+## Shortcuts
+
+Add keyboard shortcuts as text using the `data-shortcut` attribute:
+
+```html
+<rel-menubar>
+  <rel-menubar-menu label="Edit">
+    <button data-item data-shortcut="Ctrl+Z">Undo</button>
+    <button data-item data-shortcut="Ctrl+Y">Redo</button>
+  </rel-menubar-menu>
+</rel-menubar>
+```
+
+Or use `<rel-kbd>` components in the button content for better styling:
+
+```html
+<rel-menubar>
+  <rel-menubar-menu label="Edit">
+    <button data-item>
+      Undo
+      <span style="margin-left: auto; display: flex; gap: 4px;">
+        <rel-kbd size="sm">Ctrl</rel-kbd>
+        <rel-kbd size="sm">Z</rel-kbd>
+      </span>
+    </button>
+  </rel-menubar-menu>
+</rel-menubar>
+```
+
+## Data Attributes
+
+### Menu Items
+
+| Attribute | Element | Description |
+|-----------|---------|-------------|
+| `data-item` | `<button>` | Standard clickable menu item |
+| `data-separator` | `<div>` | Visual separator line |
+| `data-submenu` | `<div>` | Container for submenu items (requires `label` attribute) |
+| `data-checkbox` | `<label>` | Checkbox item (must contain `<input type="checkbox">`) |
+| `data-radio-group` | `<div>` | Radio group container (requires `name` and `value` attributes) |
+| `data-radio` | `<button>` | Radio button item (requires `value` attribute) |
+| `data-shortcut` | `<button>` | Optional keyboard shortcut text |
+
+### Properties
+
+**rel-menubar-menu**
+- `label` (string) - The text displayed on the menubar trigger button
+
+## Events
+
+### rel-menubar-change
+
+Emitted when a checkbox is toggled or a radio button is selected.
+
+**Checkbox Event Detail:**
+```typescript
+{
+  type: "checkbox",
+  label: string,    // Label text of the checkbox
+  checked: boolean  // New checked state
+}
+```
+
+**Radio Event Detail:**
+```typescript
+{
+  type: "radio",
+  name: string,     // Name of the radio group
+  value: string     // Selected value
+}
+```
+
+**Usage Example:**
+```javascript
+const menubar = document.querySelector('rel-menubar');
+menubar.addEventListener('rel-menubar-change', (event) => {
+  const { type, label, checked, name, value } = event.detail;
+
+  if (type === 'checkbox') {
+    console.log(`Checkbox "${label}" is now ${checked ? 'checked' : 'unchecked'}`);
+  } else if (type === 'radio') {
+    console.log(`Radio group "${name}" selected: ${value}`);
+  }
+});
+```
+
+## Keyboard Navigation
+
+The menubar provides comprehensive keyboard support:
+
+| Key | Context | Action |
+|-----|---------|--------|
+| `Tab` / `Shift+Tab` | Menubar | Focus menubar triggers |
+| `ArrowLeft` / `ArrowRight` | Menubar triggers | Navigate between menu triggers |
+| `Enter` / `Space` | Focused trigger | Open the menu |
+| `ArrowDown` | Open menu | Move to first item or next item |
+| `ArrowUp` | Open menu | Move to previous item |
+| `ArrowRight` | Submenu item | Open submenu |
+| `ArrowLeft` | Open submenu | Close submenu and return to parent |
+| `Escape` | Open menu | Close menu and return focus to trigger |
+| `Enter` / `Space` | Menu item | Activate item (click, toggle checkbox, select radio) |
+
+## Interaction Behavior
+
+### Opening/Closing
+- Click a trigger to open its menu
+- Click outside to close all menus
+- When a menu is open, clicking another trigger switches to it
+- When a menu is open, hovering another trigger switches to it
+
+### Submenus
+- Click or hover a submenu item to open its submenu
+- Submenu appears to the right of the parent menu
+- ArrowRight/ArrowLeft navigate in/out of submenus
+
+### State Management
+- Checkbox state is maintained in the DOM
+- Radio group value is stored on the `data-radio-group` element
+- Selected radio items receive `data-checked` attribute
+
+## Accessibility
+
+- Proper ARIA roles and keyboard navigation
+- Focus management with visual focus indicators
+- Screen reader friendly with semantic HTML
+- Disabled items are properly marked and non-interactive
+- All interactive elements are keyboard accessible
+
+## Styling Tokens
+
+The component uses design tokens from the Reliability Design System:
+
+### Colors
+- `--rel-colors-gray-light` - Menubar background
+- `--rel-colors-gray-background` - Trigger and item hover state
+- `--rel-colors-gray-border` - Borders
+- `--rel-colors-gray-divider` - Separators
+- `--rel-colors-gray-heading` - Text color
+- `--rel-colors-white` - Panel background
+- `--rel-colors-blue-primary` - Focus outline and radio selected state
+
+### Typography
+- `--rel-fontFamilies-primary` - Font family (Poppins)
+- `--rel-fontSizes-sm` - Default text size
+- `--rel-fontSizes-xs` - Shortcut text size
+- `--rel-lineHeights-sm` - Line height
+
+### Spacing
+- `--rel-spacing-space-3xs` (2px) - Menubar gap and panel padding
+- `--rel-spacing-space-2xs` (4px) - Trigger padding vertical
+- `--rel-spacing-space-xs` (8px) - Item padding vertical
+- `--rel-spacing-space-sm` (12px) - Trigger and item horizontal padding
+- `--rel-spacing-space-md` (16px) - Item padding and radio offset
+
+### Borders
+- `--rel-borders-width-stroke-100` (1px) - Border width
+- `--rel-borders-width-stroke-150` (1.5px) - Radio border
+- `--rel-borders-radius-border-radius-100` (2px) - Trigger border radius
+- `--rel-borders-radius-border-radius-200` (8px) - Panel border radius
+
+### Shadows
+- `--rel-shadows-shadow-300` - Panel drop shadow
+
+### Z-Index
+- Menu panels: `z-index: 1000`
+- Submenu panels: `z-index: 1001`
+
+## Browser Support
+
+Compatible with all modern browsers that support:
+- Web Components (Custom Elements v1)
+- Shadow DOM
+- ES2020+ features
+
+## Framework Integration
+
+Works seamlessly with:
+- Vanilla JavaScript
+- Angular
+- React (via wrapper)
+- Vue
+- Any framework that supports Web Components
+
+## Complete Example
+
+```html
+<rel-menubar id="app-menubar">
+  <rel-menubar-menu label="File">
+    <button data-item data-shortcut="Ctrl+N">New Tab</button>
+    <button data-item data-shortcut="Ctrl+Shift+N">New Window</button>
+    <div data-separator></div>
+    <div data-submenu label="Share">
+      <button data-item>Email link</button>
+      <button data-item>Messages</button>
+      <button data-item>Notes</button>
+    </div>
+    <div data-separator></div>
+    <button data-item>Close</button>
+  </rel-menubar-menu>
+
+  <rel-menubar-menu label="Edit">
+    <button data-item data-shortcut="Ctrl+Z">Undo</button>
+    <button data-item data-shortcut="Ctrl+Y">Redo</button>
+    <div data-separator></div>
+    <button data-item data-shortcut="Ctrl+X">Cut</button>
+    <button data-item data-shortcut="Ctrl+C">Copy</button>
+    <button data-item data-shortcut="Ctrl+V">Paste</button>
+  </rel-menubar-menu>
+
+  <rel-menubar-menu label="View">
+    <button data-item>Zoom In</button>
+    <button data-item>Zoom Out</button>
+    <div data-separator></div>
+    <label data-checkbox>
+      <input type="checkbox" />
+      Always Show Bookmarks Bar
+    </label>
+    <label data-checkbox>
+      <input type="checkbox" checked />
+      Always Show Full URLs
+    </label>
+    <div data-separator></div>
+    <div data-radio-group name="profile" value="andy">
+      <button data-radio value="andy">Andy</button>
+      <button data-radio value="benoit">Benoit</button>
+      <button data-radio value="luis">Luis</button>
+    </div>
+  </rel-menubar-menu>
+</rel-menubar>
+
+<script>
+  document.getElementById('app-menubar').addEventListener('rel-menubar-change', (e) => {
+    console.log('Menubar change:', e.detail);
+  });
+</script>
+```

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

@@ -0,0 +1,2 @@
+export * from "./rel-menubar";
+export * from "./rel-menubar-menu";

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

@@ -0,0 +1,16 @@
+import { LitElement, html } from "lit";
+import { customElement, property } from "lit/decorators.js";
+
+@customElement("rel-menubar-menu")
+export class RelMenubarMenu extends LitElement {
+  @property({ type: String }) label = "";
+
+  // Disable shadow DOM to allow parent to access children
+  createRenderRoot() {
+    return this;
+  }
+
+  render() {
+    return html`<slot></slot>`;
+  }
+}