@api-client/ui 0.4.2 → 0.4.3

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

@@ -0,0 +1,217 @@
+import { html, PropertyValues, TemplateResult } from 'lit'
+import { property, state } from 'lit/decorators.js'
+import { classMap } from 'lit/directives/class-map.js'
+import UiListItem from '../../list/internals/ListItem.js'
+import UiSubMenu from './SubMenu.js'
+import { findElementInShadowRoots } from '../../../lib/Dom.js'
+import { nanoid } from 'nanoid'
+
+import '@material/web/focus/md-focus-ring.js'
+import '../../ripple/ui-ripple.js'
+
+/**
+ * Material Design 3 Menu Item component.
+ *
+ * @slot - The menu item content (label, icon, etc.)
+ * @fires select - Dispatched when the menu item is selected
+ * @fires submenu-open - Dispatched when a sub-menu is opened
+ */
+export default class UiMenuItem extends UiListItem {
+  /**
+   * The ID of the associated submenu
+   * @attribute
+   */
+  @property({ type: String }) accessor submenu: string | undefined
+
+  /**
+   * Whether the menu item has a sub-menu
+   */
+  get hasSubMenu(): boolean {
+    return !!this.submenu && !!this.subMenuElement
+  }
+
+  /**
+   * Reference to the sub-menu element
+   */
+  get subMenuElement(): UiSubMenu | null {
+    if (!this.submenu) return null
+    return findElementInShadowRoots(this.submenu, this) as UiSubMenu | null
+  }
+
+  /**
+   * Whether the sub-menu is open
+   */
+  @state() protected accessor subMenuOpen = false
+
+  constructor() {
+    super()
+    this.addEventListener('mouseenter', this.handleMouseEnter.bind(this))
+    this.addEventListener('mouseleave', this.handleMouseLeave.bind(this))
+    this.addEventListener('click', this.handleMenuItemClick.bind(this))
+  }
+
+  override connectedCallback(): void {
+    super.connectedCallback()
+    this.setAttribute('role', 'menuitem')
+
+    // Generate ID if not present (needed for submenu anchoring)
+    if (!this.id) {
+      this.id = nanoid(6)
+    }
+  }
+
+  protected override updated(changedProperties: PropertyValues<this>): void {
+    super.updated(changedProperties)
+
+    if (changedProperties.has('submenu')) {
+      this.updateAccessibility()
+      this.setupSubmenuConnection()
+    }
+  }
+
+  /**
+   * Sets up the connection between this menu item and its submenu
+   */
+  protected setupSubmenuConnection(): void {
+    if (this.subMenuElement) {
+      this.subMenuElement.anchor = this.id
+
+      // Find parent menu and set it on the submenu
+      const parentMenu = this.closest('ui-menu, ui-sub-menu') as UiSubMenu
+      if (parentMenu) {
+        this.subMenuElement.setParentMenu(parentMenu)
+      }
+    }
+  }
+
+  /**
+   * Updates accessibility attributes
+   */
+  protected updateAccessibility(): void {
+    if (this.hasSubMenu) {
+      this.setAttribute('aria-haspopup', 'true')
+      this.setAttribute('aria-expanded', String(this.subMenuOpen))
+    } else {
+      this.removeAttribute('aria-haspopup')
+      this.removeAttribute('aria-expanded')
+    }
+  }
+
+  /**
+   * Handles mouse enter events
+   */
+  protected handleMouseEnter(): void {
+    if (this.hasSubMenu && !this.subMenuOpen) {
+      this.openSubMenu()
+    }
+  }
+
+  /**
+   * Handles mouse leave events
+   */
+  protected handleMouseLeave(): void {
+    // Close sub-menu after a delay to allow moving to sub-menu
+    setTimeout(() => {
+      if (this.subMenuOpen && !this.matches(':hover') && !this.subMenuElement?.matches(':hover')) {
+        this.closeSubMenu()
+      }
+    }, 100)
+  }
+
+  /**
+   * Handles click events
+   */
+  public override handleClick(e: MouseEvent): void {
+    if (this.hasSubMenu) {
+      e.preventDefault()
+      e.stopPropagation()
+      this.toggleSubMenu()
+    } else {
+      super.handleClick(e)
+    }
+  }
+
+  /**
+   * Handles menu item click events
+   */
+  protected handleMenuItemClick(e: MouseEvent): void {
+    this.handleClick(e)
+  }
+
+  /**
+   * Opens the sub-menu
+   */
+  openSubMenu(): void {
+    if (!this.hasSubMenu || this.subMenuOpen) return
+
+    this.subMenuOpen = true
+    this.updateAccessibility()
+    this.subMenuElement?.show()
+
+    this.dispatchEvent(
+      new CustomEvent('submenu-open', {
+        detail: { subMenu: this.subMenuElement },
+        bubbles: true,
+        composed: true,
+      })
+    )
+  }
+
+  /**
+   * Closes the sub-menu
+   */
+  closeSubMenu(): void {
+    if (!this.subMenuOpen) return
+
+    this.subMenuOpen = false
+    this.updateAccessibility()
+    this.subMenuElement?.hide()
+  }
+
+  /**
+   * Toggles the sub-menu
+   */
+  toggleSubMenu(): void {
+    if (this.subMenuOpen) {
+      this.closeSubMenu()
+    } else {
+      this.openSubMenu()
+    }
+  }
+
+  /**
+   * Handles sub-menu item selection
+   */
+  protected handleSubMenuSelect(e: CustomEvent): void {
+    // Bubble up the selection event
+    this.dispatchEvent(
+      new CustomEvent('select', {
+        detail: e.detail,
+        bubbles: true,
+        composed: true,
+      })
+    )
+  }
+
+  override render(): TemplateResult {
+    const classes = classMap({
+      'surface': true,
+      'menu-item': true,
+      'menu-item-with-submenu': this.hasSubMenu,
+      'submenu-open': this.subMenuOpen,
+    })
+
+    return html`
+      ${this.renderFocusRing()} ${this.renderRipple()}
+      <div class=${classes} role="menuitem">${this.renderStart()} ${this.renderBody()} ${this.renderEnd()}</div>
+    `
+  }
+
+  protected override renderEnd(): TemplateResult {
+    return html`<div class="end">
+      <slot name="end" @slotchange=${this.handleSlotChange}></slot>
+      <span class="trailing-supporting-text"><slot name="end-text"></slot></span>
+      ${this.hasSubMenu ? html`<ui-icon class="menu-item-arrow">arrow_right</ui-icon>` : ''}
+    </div>`
+  }
+}

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

@@ -0,0 +1,8 @@
+import { css } from 'lit'
+
+export default css`
+  :host {
+    position-area: span-bottom right;
+    position-try-fallbacks: flip-block flip-inline;
+  }
+`

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

@@ -0,0 +1,179 @@
+import { html, PropertyValues, TemplateResult } from 'lit'
+import { property } from 'lit/decorators.js'
+import { classMap } from 'lit/directives/class-map.js'
+import Menu from './Menu.js'
+import UiListItem from '../../list/internals/ListItem.js'
+import { findElementInShadowRoots } from '../../../lib/Dom.js'
+import type { MenuItem } from '../../../index.js'
+
+/**
+ * Material Design 3 Sub-Menu component.
+ * Extends the main Menu component to provide sub-menu functionality.
+ * Uses Popover API and Anchor Positioning API for modern positioning.
+ *
+ * @slot - The sub-menu items
+ * @fires select - Dispatched when a sub-menu item is selected
+ * @fires close - Dispatched when the sub-menu is closed
+ */
+export default class UiSubMenu extends Menu {
+  /**
+   * The ID of the anchor element (parent menu item)
+   * @attribute
+   */
+  @property({ type: String }) accessor anchor: string | undefined
+
+  /**
+   * Reference to the parent menu
+   */
+  parentMenu: Menu | null = null
+
+  /**
+   * Reference to the anchor element
+   */
+  get anchorElement(): MenuItem | null {
+    if (!this.anchor) return null
+    return findElementInShadowRoots(this.anchor, this) as MenuItem | null
+  }
+
+  override connectedCallback(): void {
+    super.connectedCallback()
+    this.setAttribute('role', 'menu')
+    this.setAttribute('aria-label', 'Submenu')
+  }
+
+  protected override updated(changedProperties: PropertyValues<this>): void {
+    super.updated(changedProperties)
+
+    if (changedProperties.has('anchor')) {
+      this.updateAnchorPositioning()
+    }
+  }
+
+  /**
+   * Updates anchor positioning using CSS Anchor Positioning API
+   */
+  protected updateAnchorPositioning(): void {
+    const anchor = this.anchorElement
+    if (!anchor) return
+    const anchorName = `--anchor-${this.id}`
+
+    // Set anchor name on the parent menu item
+    anchor.style.setProperty('anchor-name', anchorName)
+
+    // Set anchor positioning on the submenu
+    this.style.setProperty('position-anchor', anchorName)
+  }
+
+  /**
+   * Shows the submenu
+   */
+  override show(): void {
+    if (!this.anchorElement) {
+      return
+    }
+
+    // Update positioning before showing
+    this.updateAnchorPositioning()
+
+    // Close any other open submenus in the parent menu
+    if (this.parentMenu) {
+      this.parentMenu.closeSubMenu()
+      this.parentMenu.setActiveSubMenu(this)
+    }
+
+    // Show the popover
+    this.showPopover()
+    this.open = true
+    this.focus()
+
+    this.dispatchEvent(
+      new CustomEvent('open', {
+        bubbles: true,
+        composed: true,
+        detail: { submenu: this },
+      })
+    )
+  }
+
+  /**
+   * Hides the submenu
+   */
+  override hide(): void {
+    super.hide()
+
+    // Clear parent menu's active submenu reference
+    const parentMenu = this.parentMenu
+    if (parentMenu) {
+      parentMenu.setActiveSubMenu(null)
+    }
+    const anchor = this.anchorElement
+    if (anchor) {
+      anchor.closeSubMenu()
+    }
+  }
+
+  /**
+   * Sets the parent menu reference
+   */
+  setParentMenu(menu: Menu): void {
+    this.parentMenu = menu
+  }
+
+  /**
+   * Handles selection events - bubbles them up to parent menu
+   */
+  override notifySelect(item: UiListItem): boolean {
+    // First hide this submenu
+    this.hide()
+
+    // If we have a parent menu, hide it too and bubble the selection
+    if (this.parentMenu) {
+      this.parentMenu.hide()
+    }
+
+    // Call parent implementation to dispatch the select event
+    return super.notifySelect(item)
+  }
+
+  /**
+   * Handles keyboard navigation specific to submenus
+   */
+  override handleKeydown(e: KeyboardEvent): void {
+    if (!this.open || e.defaultPrevented) return
+
+    switch (e.key) {
+      case 'Escape':
+        e.preventDefault()
+        this.hide()
+        // Return focus to parent menu item
+        if (this.anchorElement) {
+          this.anchorElement.focus()
+        }
+        break
+      case 'ArrowLeft':
+        e.preventDefault()
+        this.hide()
+        // Return focus to parent menu item
+        if (this.anchorElement) {
+          this.anchorElement.focus()
+        }
+        break
+      default:
+        // Let the parent handle other keys
+        super.handleKeydown(e)
+    }
+  }
+
+  override render(): TemplateResult {
+    const classes = classMap({
+      'submenu-container': true,
+      'submenu-open': this.open,
+    })
+
+    return html`
+      <div class=${classes}>
+        <slot></slot>
+      </div>
+    `
+  }
+}

package/src/md/menu/ui-menu-item.ts

@@ -0,0 +1,25 @@
+import type { CSSResultOrNative } from 'lit'
+import { customElement } from 'lit/decorators.js'
+import Element from './internal/MenuItem.js'
+import styles from './internal/MenuItem.styles.js'
+import listStyles from '../list/internals/ListItem.styles.js'
+
+/**
+ * Material Design 3 Menu Item component.
+ *
+ * @element ui-menu-item
+ * @attribute {Object} data - The menu item data object
+ * @attribute {boolean} disabled - Whether the menu item is disabled
+ * @fires select - Dispatched when the menu item is selected
+ * @fires submenu-open - Dispatched when a sub-menu is opened
+ */
+@customElement('ui-menu-item')
+export class UiMenuItemElement extends Element {
+  static override styles: CSSResultOrNative[] = [styles, listStyles]
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'ui-menu-item': UiMenuItemElement
+  }
+}

package/src/md/menu/ui-menu.ts

@@ -0,0 +1,26 @@
+import type { CSSResultOrNative } from 'lit'
+import { customElement } from 'lit/decorators.js'
+import Element from './internal/Menu.js'
+import styles from './internal/Menu.styles.js'
+
+/**
+ * Material Design 3 Menu component with sub-menu support.
+ *
+ * @element ui-menu
+ * @attribute {boolean} open - Whether the menu is currently open
+ * @attribute {boolean} anchored - Whether the menu should be positioned relative to an anchor element
+ * @attribute {boolean} disabled - Whether the menu is disabled
+ * @fires select - Dispatched when a menu item is selected
+ * @fires close - Dispatched when the menu is closed
+ * @fires open - Dispatched when the menu is opened
+ */
+@customElement('ui-menu')
+export class UiMenuElement extends Element {
+  static override styles: CSSResultOrNative[] = [styles]
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'ui-menu': UiMenuElement
+  }
+}

package/src/md/menu/ui-sub-menu.ts

@@ -0,0 +1,25 @@
+import type { CSSResultOrNative } from 'lit'
+import { customElement } from 'lit/decorators.js'
+import Element from './internal/SubMenu.js'
+import menuStyles from './internal/SubMenu.styles.js'
+import styles from './internal/Menu.styles.js'
+
+/**
+ * Material Design 3 Sub-Menu component.
+ *
+ * @element ui-sub-menu
+ * @attribute {Object} parentItem - The parent menu item element
+ * @attribute {Array} menuItems - The sub-menu items data
+ * @fires select - Dispatched when a sub-menu item is selected
+ * @fires close - Dispatched when the sub-menu is closed
+ */
+@customElement('ui-sub-menu')
+export class UiSubMenuElement extends Element {
+  static override styles: CSSResultOrNative[] = [styles, menuStyles]
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'ui-sub-menu': UiSubMenuElement
+  }
+}