@api-client/ui 0.4.1 → 0.4.3

package/src/md/menu/README.md

@@ -0,0 +1,253 @@
+# UI Menu Components
+
+A set of accessible, themeable, and modern menu components for the web, built as Lit web components. This package includes `<ui-menu>`, `<ui-menu-item>`, and `<ui-sub-menu>` to create simple dropdowns or complex, deeply-nested contextual menus.
+
+The implementation leverages modern web platform features like the **Popover API** for overlay management and the **CSS Anchor Positioning API** for robust submenu placement, with built-in fallbacks for older browsers.
+
+## Features
+
+- **Modern & Performant**: Built on top of the native Popover API.
+- **Flexible Positioning**: Uses the CSS Anchor Positioning API for precise submenu placement, avoiding complex JavaScript calculations.
+- **Clean HTML Structure**: Submenus are linked via attributes (`id`, `submenu`, `anchor`), not nested in slots, leading to a flatter and more maintainable DOM.
+- **Deep Nesting**: Supports multiple levels of submenus out of the box.
+- **Accessible**: Follows WAI-ARIA patterns for menus, with full keyboard navigation support.
+- **Themeable**: Style the components using CSS Custom Properties to match your design system.
+
+## Usage
+
+### Basic Menu
+
+To create a simple menu, use a trigger element (like `<ui-button>`) and a `<ui-menu>` element. The trigger connects to the menu by setting its `popovertarget` attribute to the `id` of the menu.
+
+```html
+<!-- Trigger Button -->
+<ui-button id="basic-menu-trigger" popovertarget="basic-menu">
+  Open Menu
+</ui-button>
+
+<!-- Menu -->
+<ui-menu id="basic-menu">
+  <ui-menu-item>
+    <span slot="start"><ui-icon>add</ui-icon></span>
+    <span>New</span>
+  </ui-menu-item>
+  <ui-menu-item>
+    <span slot="start"><ui-icon>folder</ui-icon></span>
+    <span>Open</span>
+  </ui-menu-item>
+  <ui-menu-item disabled>
+    <span slot="start"><ui-icon>save</ui-icon></span>
+    <span>Save (Disabled)</span>
+  </ui-menu-item>
+  <div role="separator" style="height: 1px; background: #ccc; margin: 8px 0;"></div>
+  <ui-menu-item>
+    <span slot="start"><ui-icon>print</ui-icon></span>
+    <span>Print</span>
+  </ui-menu-item>
+</ui-menu>
+
+<script>
+  document.querySelector('#basic-menu').addEventListener('select', (e) => {
+    const { item, index } = e.detail;
+    console.log(`Selected: "${item.textContent.trim()}" at index ${index}`);
+  });
+</script>
+```
+
+### Menu with Submenus
+
+For menus with nested submenus, the components use an attribute-based relationship for a clean and flexible structure.
+
+1. Give the parent `<ui-menu-item>` an `id`.
+2. Add a `submenu` attribute to the `<ui-menu-item>` pointing to the id of the `<ui-sub-menu>`.
+3. Add an `anchor` attribute to the `<ui-sub-menu>` pointing back to the id of its parent `<ui-menu-item>`.
+4. **Important**: Place the `<ui-sub-menu>` elements inside the light DOM of the parent `<ui-menu>` (as children of the main menu element), not as separate standalone elements.
+
+This approach allows for deep nesting and ensures proper keyboard event propagation. The submenus must be children of the parent menu for keyboard navigation to work correctly across menu levels.
+
+```html
+<!-- Trigger Button -->
+<ui-button id="submenu-trigger" popovertarget="submenu-demo">
+  Open Menu
+</ui-button>
+
+<!-- Main Menu -->
+<ui-menu id="submenu-demo" @select="handleNestedMenuSelect">
+  <!-- Menu Item with a Submenu -->
+  <ui-menu-item id="file-item" submenu="file-submenu">
+    <span slot="start"><ui-icon>docs</ui-icon></span>
+    <span>File</span>
+  </ui-menu-item>
+  <ui-menu-item id="edit-item" submenu="edit-submenu">
+    <span slot="start"><ui-icon>edit</ui-icon></span>
+    <span>Edit</span>
+  </ui-menu-item>
+  <ui-menu-item>
+    <span slot="start"><ui-icon>visibility</ui-icon></span>
+    <span>View</span>
+  </ui-menu-item>
+
+  <!-- File Submenu (inside the main menu's light DOM) -->
+  <ui-sub-menu id="file-submenu" anchor="file-item">
+    <ui-menu-item>New File</ui-menu-item>
+    <ui-menu-item>Open File</ui-menu-item>
+    <!-- Nested Submenu Item -->
+    <ui-menu-item id="export-item" submenu="export-submenu">
+      <span slot="start"><ui-icon>file_export</ui-icon></span>
+      <span>Export</span>
+    </ui-menu-item>
+
+    <!-- Deeply Nested Export Submenu (inside the file submenu) -->
+    <ui-sub-menu id="export-submenu" anchor="export-item">
+      <ui-menu-item>Export as PDF</ui-menu-item>
+      <ui-menu-item>Export as PNG</ui-menu-item>
+    </ui-sub-menu>
+  </ui-sub-menu>
+
+  <!-- Edit Submenu (inside the main menu's light DOM) -->
+  <ui-sub-menu id="edit-submenu" anchor="edit-item">
+    <ui-menu-item>Undo</ui-menu-item>
+    <ui-menu-item>Redo</ui-menu-item>
+    <ui-menu-item>Cut</ui-menu-item>
+  </ui-sub-menu>
+</ui-menu>
+```
+
+## Components
+
+### `<ui-menu>`
+
+The main menu container that holds menu items and submenus.
+
+#### Menu Attributes
+
+- `open` (boolean) - Whether the menu is currently open
+- `disabled` (boolean) - Whether the menu is disabled
+- `popover` (string) - Native popover attribute, typically set to "auto"
+- `id` (string) - Required for popover targeting
+
+#### Menu Events
+
+- `select` - Dispatched when a menu item is selected. Event detail contains `{ item, index }`
+- `open` - Dispatched when the menu is opened
+- `close` - Dispatched when the menu is closed
+
+#### Menu Methods
+
+- `show()` - Programmatically show the menu
+- `hide()` - Programmatically hide the menu
+- `togglePopover(force?)` - Toggle the menu's popover state
+
+### `<ui-menu-item>`
+
+Individual menu items that can trigger actions or open submenus.
+
+#### Menu Item Attributes
+
+- `disabled` (boolean) - Whether the menu item is disabled
+- `submenu` (string) - ID of the associated submenu element
+- `id` (string) - Required when the item has a submenu (for anchoring)
+
+#### Menu Item Slots
+
+- Default slot - The main content of the menu item
+- `start` - Content before the main text (e.g., icons)
+- `end` - Content after the main text
+- `end-text` - Supporting text at the end
+
+#### Menu Item Events
+
+- `select` - Dispatched when the menu item is clicked (if no submenu)
+- `submenu-open` - Dispatched when a submenu is opened
+
+### `<ui-sub-menu>`
+
+Submenu containers that extend the main menu component with additional positioning logic.
+
+#### Sub-menu Attributes
+
+- `anchor` (string) - ID of the parent menu item that this submenu is anchored to
+- `open` (boolean) - Whether the submenu is currently open
+- `disabled` (boolean) - Whether the submenu is disabled
+- `popover` (string) - Native popover attribute, typically set to "auto"
+- `id` (string) - Required for menu item targeting
+
+#### Sub-menu Events
+
+- `select` - Dispatched when a submenu item is selected
+- `open` - Dispatched when the submenu is opened  
+- `close` - Dispatched when the submenu is closed
+
+#### Sub-menu Methods
+
+- `show()` - Programmatically show the submenu
+- `hide()` - Programmatically hide the submenu
+- `setParentMenu(menu)` - Set the parent menu for proper event handling
+
+## Keyboard Navigation
+
+The menu components support full keyboard navigation:
+
+- **Arrow Keys**: Navigate between menu items
+- **Enter/Space**: Select a menu item or open a submenu
+- **Arrow Right**: Open a submenu (when focused on an item with submenu)
+- **Arrow Left**: Close current submenu and return to parent
+- **Escape**: Close the current menu/submenu
+- **Home/End**: Jump to first/last menu item
+
+## Styling
+
+The components can be styled using CSS Custom Properties. Key styling hooks include:
+
+```css
+ui-menu {
+  --md-menu-container-color: white;
+  --md-menu-container-elevation: 2;
+  --md-menu-item-height: 48px;
+  /* ... other custom properties */
+}
+```
+
+## Accessibility
+
+The menu components follow WAI-ARIA best practices:
+
+- Menu containers have `role="menu"`
+- Menu items have `role="menuitem"`
+- Items with submenus have `aria-haspopup="true"` and `aria-expanded` attributes
+- Full keyboard navigation is supported
+- Proper focus management when opening/closing menus
+- Screen reader announcements for menu state changes
+
+## Best Practices
+
+### Structure Requirements
+
+1. **Light DOM Placement**: Always place `<ui-sub-menu>` elements inside the light DOM of their parent `<ui-menu>` or `<ui-sub-menu>`. This ensures proper keyboard event propagation.
+
+2. **ID Management**: Ensure menu items that have submenus have unique `id` attributes, and their corresponding submenus reference them via the `anchor` attribute.
+
+3. **Popover Attributes**: Include `popover="auto"` on both `<ui-menu>` and `<ui-sub-menu>` elements for proper native popover behavior.
+
+### Event Handling
+
+```javascript
+// Listen for menu selections
+document.querySelector('#my-menu').addEventListener('select', (e) => {
+  const { item, index } = e.detail;
+  console.log(`Selected: "${item.textContent.trim()}" at index ${index}`);
+});
+```
+
+### Trigger Connection
+
+Connect triggers to menus using the native `popovertarget` attribute:
+
+```html
+<ui-button popovertarget="my-menu">Open Menu</ui-button>
+<ui-menu id="my-menu">
+  <!-- menu items -->
+</ui-menu>
+```
+
+This leverages the native Popover API for optimal performance and browser integration.

package/src/md/menu/index.ts

@@ -0,0 +1,3 @@
+export { UiMenuElement } from './ui-menu.js'
+export { UiMenuItemElement } from './ui-menu-item.js'
+export { UiSubMenuElement } from './ui-sub-menu.js'

package/src/md/menu/internal/Menu.styles.ts

@@ -0,0 +1,185 @@
+import { css } from 'lit'
+
+export default css`
+  :host {
+    display: none;
+    position-area: bottom span-right;
+    position-try: normal flip-block;
+    position: absolute;
+    margin: 0;
+    padding: 0;
+    border: none;
+  }
+
+  :host(:popover-open) {
+    display: block;
+    background-color: var(--md-sys-color-surface);
+    border-radius: var(--md-sys-shape-corner-extra-small);
+    box-shadow: var(--md-sys-elevation-3);
+  }
+
+  .menu-container {
+    min-width: 200px;
+    padding: 8px 0;
+    outline: none;
+  }
+
+  .menu-divider {
+    height: 1px;
+    background-color: var(--md-sys-color-outline-variant);
+    margin: 8px 0;
+  }
+
+  /* Menu Item Styles */
+  .menu-item {
+    position: relative;
+    display: flex;
+    align-items: center;
+    min-height: 48px;
+    padding: 0 16px;
+    cursor: pointer;
+    outline: none;
+    transition: background-color 0.2s ease;
+  }
+
+  .menu-item:hover {
+    background-color: var(--md-sys-color-surface-variant);
+  }
+
+  .menu-item:focus {
+    background-color: var(--md-sys-color-surface-variant);
+  }
+
+  .menu-item[disabled] {
+    opacity: 0.38;
+    cursor: not-allowed;
+    pointer-events: none;
+  }
+
+  .menu-item-content {
+    display: flex;
+    align-items: center;
+    width: 100%;
+    gap: 12px;
+  }
+
+  .menu-item-icon {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 24px;
+    height: 24px;
+    color: var(--md-sys-color-on-surface);
+    font-size: 20px;
+  }
+
+  .menu-item-label {
+    flex: 1;
+    color: var(--md-sys-color-on-surface);
+    font-family: var(--md-sys-typescale-label-large-font-family-name);
+    font-size: var(--md-sys-typescale-label-large-font-size);
+    font-weight: var(--md-sys-typescale-label-large-font-weight);
+    line-height: var(--md-sys-typescale-label-large-line-height);
+    letter-spacing: var(--md-sys-typescale-label-large-letter-spacing);
+  }
+
+  .menu-item-arrow {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 24px;
+    height: 24px;
+    color: var(--md-sys-color-on-surface);
+    font-size: 18px;
+    font-weight: 500;
+  }
+
+  .menu-item-with-submenu {
+    position: relative;
+  }
+
+  .menu-item-with-submenu:hover .menu-item-arrow {
+    color: var(--md-sys-color-primary);
+  }
+
+  /* Sub-menu Styles */
+  .submenu-container {
+    min-width: 200px;
+    max-width: 320px;
+    background-color: var(--md-sys-color-surface);
+    border-radius: var(--md-sys-shape-corner-extra-small);
+    box-shadow: var(--md-sys-elevation-level3);
+    padding: 8px 0;
+  }
+
+  /* Submenu positioning with Anchor API */
+  ui-sub-menu {
+    display: none;
+  }
+
+  ui-sub-menu:popover-open {
+    display: block;
+    background-color: var(--md-sys-color-surface);
+    border-radius: var(--md-sys-shape-corner-extra-small);
+    box-shadow: var(--md-sys-elevation-level3);
+    min-width: 200px;
+    max-width: 320px;
+    padding: 8px 0;
+    z-index: 1000;
+  }
+
+  /* Fallback positioning for browsers without anchor positioning */
+  @supports not (anchor-name: --test) {
+    ui-sub-menu:popover-open {
+      position: fixed;
+      transform: translateX(200px);
+    }
+  }
+
+  /* Focus Ring */
+  md-focus-ring {
+    --md-focus-ring-color: var(--md-sys-color-primary);
+    --md-focus-ring-width: 2px;
+  }
+
+  /* Ripple Effect */
+  ui-ripple {
+    --md-ripple-color: var(--md-sys-color-primary);
+    --md-ripple-opacity: 0.12;
+  }
+
+  /* Responsive Design */
+  @media (max-width: 600px) {
+    .menu-container {
+      min-width: 180px;
+      max-width: 280px;
+    }
+
+    .submenu-container {
+      min-width: 180px;
+      max-width: 280px;
+    }
+  }
+
+  /* High Contrast Mode */
+  @media (prefers-contrast: high) {
+    .menu-container {
+      border: 1px solid var(--md-sys-color-outline);
+    }
+
+    .submenu-container {
+      border: 1px solid var(--md-sys-color-outline);
+    }
+
+    .menu-divider {
+      background-color: var(--md-sys-color-outline);
+    }
+  }
+
+  /* Reduced Motion */
+  @media (prefers-reduced-motion: reduce) {
+    .menu-item {
+      transition: none;
+    }
+  }
+`

package/src/md/menu/internal/Menu.ts

@@ -0,0 +1,205 @@
+import { html, PropertyValues, TemplateResult } from 'lit'
+import { property, state, queryAssignedElements } from 'lit/decorators.js'
+import { classMap } from 'lit/directives/class-map.js'
+import { nanoid } from 'nanoid'
+import UiList from '../../list/internals/List.js'
+import UiMenuItem from './MenuItem.js'
+import UiSubMenu from './SubMenu.js'
+import { setDisabled } from '../../../lib/disabled.js'
+import UiListItem from '../../list/internals/ListItem.js'
+import { bound } from '../../../decorators/bound.js'
+
+/**
+ * Material Design 3 Menu component with sub-menu support.
+ * Uses Popover API and Anchor Positioning API for modern positioning.
+ *
+ * @fires select - Dispatched when a menu item is selected
+ * @fires close - Dispatched when the menu is closed
+ */
+export default class Menu extends UiList {
+  /**
+   * Whether the menu is currently open
+   * @attribute
+   */
+  @property({ type: Boolean, reflect: true }) accessor open = false
+
+  /**
+   * Whether the menu is disabled
+   * @attribute
+   */
+  @property({ type: Boolean, reflect: true }) accessor disabled = false
+
+  /**
+   * Currently active sub-menu
+   */
+  @state() accessor activeSubMenu: UiSubMenu | null = null
+
+  /**
+   * Assigned menu items from light DOM
+   */
+  @queryAssignedElements({ selector: 'ui-menu-item' }) protected accessor assignedMenuItems!: UiMenuItem[]
+
+  constructor() {
+    super()
+    this.selector = 'ui-menu-item'
+    this.ariaExpanded = 'false'
+    this.addEventListener('beforetoggle', this.handleBeforeToggle.bind(this))
+  }
+
+  override connectedCallback(): void {
+    super.connectedCallback()
+    this.setAttribute('role', 'menu')
+    this.setAttribute('tabindex', '-1')
+    if (!this.hasAttribute('popover')) {
+      this.setAttribute('popover', 'auto')
+    }
+    if (!this.id) {
+      this.id = nanoid()
+    }
+  }
+
+  protected override updated(changedProperties: PropertyValues<this>): void {
+    super.updated(changedProperties)
+
+    if (changedProperties.has('disabled')) {
+      setDisabled(this, this.disabled)
+    }
+  }
+
+  override togglePopover(force?: boolean): boolean {
+    this.open = !this.open
+    this.ariaExpanded = String(this.open)
+    this.tabIndex = this.open ? 0 : -1
+    if (this.open) {
+      this.focus()
+    }
+    return super.togglePopover(force)
+  }
+
+  /**
+   * Shows the menu
+   */
+  show(): void {
+    this.tabIndex = 0 // Make menu focusable
+    this.ariaExpanded = 'true'
+    this.showPopover()
+    this.open = true
+    this.focus()
+    this.dispatchEvent(new CustomEvent('open', { bubbles: false, composed: true }))
+  }
+
+  /**
+   * Hides the menu
+   */
+  hide(): void {
+    this.tabIndex = -1
+    this.ariaExpanded = 'false'
+    this.hidePopover()
+    this.open = false
+    this.closeSubMenu()
+    this.dispatchEvent(new CustomEvent('close', { bubbles: false, composed: true }))
+  }
+
+  /**
+   * Handles beforetoggle event from popover
+   */
+  protected handleBeforeToggle(e: Event): void {
+    const toggleEvent = e as ToggleEvent
+    if (toggleEvent.newState === 'closed') {
+      this.open = false
+      this.closeSubMenu()
+    }
+  }
+
+  /**
+   * Handles keyboard navigation for the menu
+   */
+  override handleKeydown(e: KeyboardEvent): void {
+    if (!this.open || e.defaultPrevented) return
+
+    switch (e.key) {
+      case 'Escape':
+        e.preventDefault()
+        this.hide()
+        break
+      case 'ArrowRight':
+        e.preventDefault()
+        this.openSubMenu()
+        break
+      case 'ArrowLeft':
+        e.preventDefault()
+        this.closeSubMenu()
+        break
+      default:
+        // Let the parent UiList handle other keys
+        super.handleKeydown(e)
+    }
+  }
+
+  @bound
+  handleSubMenuSelect(e: CustomEvent): void {
+    super.notifySelect(e.detail.item, e.detail.index)
+  }
+
+  /**
+   * Opens the sub-menu for the currently active item
+   */
+  protected openSubMenu(): void {
+    const activeItem = this.activeListItem as UiMenuItem
+    if (activeItem?.hasSubMenu) {
+      activeItem.openSubMenu()
+    }
+  }
+
+  /**
+   * Closes the currently open sub-menu
+   */
+  closeSubMenu(): void {
+    if (this.activeSubMenu) {
+      this.activeSubMenu.removeEventListener('select', this.handleSubMenuSelect as EventListener)
+      this.activeSubMenu.hide()
+      this.activeSubMenu = null
+    }
+  }
+
+  /**
+   * Sets the active sub-menu
+   */
+  setActiveSubMenu(subMenu: UiSubMenu | null): void {
+    this.activeSubMenu = subMenu
+    subMenu?.addEventListener('select', this.handleSubMenuSelect as EventListener)
+  }
+
+  override notifySelect(item: UiListItem, index?: number): boolean {
+    this.hide()
+    return super.notifySelect(item, index)
+  }
+
+  /**
+   * Handles sub-menu opening
+   */
+  protected handleSubMenuOpen(e: CustomEvent): void {
+    const subMenu = e.detail.subMenu
+    this.setActiveSubMenu(subMenu)
+  }
+
+  /**
+   * Handles slot changes to update menu items
+   */
+  protected handleSlotChange(): void {
+    // Update the items list when slot content changes
+    this.updateItems()
+  }
+
+  override render(): TemplateResult {
+    const classes = classMap({
+      'menu-container': true,
+    })
+
+    return html`
+      <div class=${classes}>
+        <slot @slotchange=${this.handleSlotChange}></slot>
+      </div>
+    `
+  }
+}

package/src/md/menu/internal/MenuItem.styles.ts

@@ -0,0 +1,64 @@
+import { css } from 'lit'
+
+export default css`
+  :host {
+    display: block;
+    position: relative;
+  }
+
+  .menu-item {
+    position: relative;
+    display: flex;
+    align-items: center;
+    min-height: 48px;
+    padding: 0 16px;
+    cursor: pointer;
+    outline: none;
+    transition: background-color 0.2s ease;
+  }
+
+  .menu-item:hover {
+    background-color: var(--md-sys-color-surface-variant);
+  }
+
+  .menu-item:focus {
+    background-color: var(--md-sys-color-surface-variant);
+  }
+
+  .menu-item[disabled] {
+    opacity: 0.38;
+    cursor: not-allowed;
+    pointer-events: none;
+  }
+
+  .menu-item-with-submenu {
+    position: relative;
+  }
+
+  .menu-item-with-submenu:hover .menu-item-arrow {
+    color: var(--md-sys-color-primary);
+  }
+
+  .menu-item-arrow {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: 24px;
+    height: 24px;
+    color: var(--md-sys-color-on-surface);
+    font-size: 18px;
+    font-weight: 500;
+  }
+
+  /* Focus Ring */
+  md-focus-ring {
+    --md-focus-ring-color: var(--md-sys-color-primary);
+    --md-focus-ring-width: 2px;
+  }
+
+  /* Ripple Effect */
+  ui-ripple {
+    --md-ripple-color: var(--md-sys-color-primary);
+    --md-ripple-opacity: 0.12;
+  }
+`