@m3e/menu 1.0.0-rc.1 → 1.0.0-rc.2

package/src/MenuItemCheckboxElement.ts

@@ -1,178 +0,0 @@
-import { css, CSSResultGroup, html } from "lit";
-import { customElement } from "lit/decorators.js";
-
-import { Checked, hasAssignedNodes, Role } from "@m3e/core";
-
-import { M3eMenuItemElement } from "./MenuItemElement";
-import { MenuItemElementBase } from "./MenuItemElementBase";
-
-/**
- * @summary
- * An item of a menu which supports a checkable state.
- *
- * @description
- * The `m3e-menu-item-checkbox` component represents a menu item that supports an independent checkable state.
- * It allows users to toggle options on or off without affecting other items in the menu, making it ideal for
- * multi-select scenarios such as filters, visibility toggles, or feature flags. This component encodes a persistent
- * selection contract and can coexist with other checkbox or radio items within the same menu.
- *
- * @example
- * The following example illustrates use of the `m3e-menu-item-checkbox` to present multiple independent checkable
- * items in a menu.
- * ```html
- * <m3e-button>
- *   <m3e-menu-trigger for="menu">Format</m3e-menu-trigger>
- * </m3e-button>
- * <m3e-menu id="menu">
- *   <m3e-menu-item-checkbox>Bold</m3e-menu-item-checkbox>
- *   <m3e-menu-item-checkbox>Italic</m3e-menu-item-checkbox>
- *   <m3e-menu-item-checkbox>Underline</m3e-menu-item-checkbox>
- * </m3e-menu>
- * ```
- *
- * @tag m3e-menu-item-checkbox
- *
- * @slot - Renders the label of the item.
- * @slot icon - Renders an icon before the items's label.
- * @slot trailing-icon - Renders an icon after the item's label.
- *
- * @attr disabled - Whether the element is disabled.
- * @attr checked - Whether the element is checked.
- *
- * @cssprop --m3e-menu-item-container-height - Height of the menu item container.
- * @cssprop --m3e-menu-item-color - Text color for unselected, enabled menu items.
- * @cssprop --m3e-menu-item-container-hover-color - State layer hover color for unselected items.
- * @cssprop --m3e-menu-item-container-focus-color - State layer focus color for unselected items.
- * @cssprop --m3e-menu-item-ripple-color - Ripple color for unselected items.
- * @cssprop --m3e-menu-selected-color - Text color for selected or expanded items.
- * @cssprop --m3e-menu-selected-container-color - Background color for selected or expanded items.
- * @cssprop --m3e-menu-item-selected-container-hover-color - State layer hover color for selected items.
- * @cssprop --m3e-menu-item-selected-container-focus-color - State layer focus color for selected items.
- * @cssprop --m3e-menu-item-selected-ripple-color - Ripple color for selected items.
- * @cssprop --m3e-menu-item-disabled-color - Base color for disabled items.
- * @cssprop --m3e-menu-item-disabled-opacity - Opacity percentage for disabled item color mix.
- * @cssprop --m3e-menu-item-icon-label-space - Horizontal gap between icon and content.
- * @cssprop --m3e-menu-item-padding-start - Start padding for the item wrapper.
- * @cssprop --m3e-menu-item-padding-end - End padding for the item wrapper.
- * @cssprop --m3e-menu-item-label-text-font-size - Font size for menu item text.
- * @cssprop --m3e-menu-item-label-text-font-weight - Font weight for menu item text.
- * @cssprop --m3e-menu-item-label-text-line-height - Line height for menu item text.
- * @cssprop --m3e-menu-item-label-text-tracking - Letter spacing for menu item text.
- * @cssprop --m3e-menu-item-focus-ring-shape - Border radius for the focus ring.
- * @cssprop --m3e-menu-item-icon-size - Font size for leading and trailing icons.
- */
-@customElement("m3e-menu-item-checkbox")
-export class M3eMenuItemCheckboxElement extends Checked(Role(MenuItemElementBase, "menuitemcheckbox")) {
-  /** The styles of the element. */
-  static override styles: CSSResultGroup = [
-    MenuItemElementBase.styles,
-    css`
-      .icon {
-        display: flex;
-        align-items: center;
-        justify-content: center;
-      }
-      :host(:not(.-with-icon)) .icon {
-        margin-inline-start: calc(0px - var(--m3e-menu-item-icon-label-space, 0.75rem));
-      }
-      .check {
-        width: 1em;
-        font-size: var(--m3e-menu-item-icon-size, 1.5rem) !important;
-      }
-      :host(:not([checked])) .check {
-        display: none;
-      }
-      :host([checked]) .icon {
-        margin-inline-start: 0;
-      }
-      :host([checked]) ::slotted([slot="icon"]) {
-        display: none !important;
-      }
-    `,
-  ];
-
-  /** @internal */ readonly #clickHandler = (e: Event) => this.#handleClick(e);
-  /** @internal */ readonly #keyDownHandler = (e: KeyboardEvent) => this.#handleKeyDown(e);
-  /** @internal */ readonly #keyUpHandler = () => this.#handleKeyUp();
-  /** @internal */ readonly #mouseEnterHandler = () => this.#handleMouseEnter();
-  /** @internal */ #spacePressed = false;
-
-  /** @inheritdoc */
-  override connectedCallback(): void {
-    super.connectedCallback();
-
-    this.addEventListener("click", this.#clickHandler);
-    this.addEventListener("keydown", this.#keyDownHandler);
-    this.addEventListener("keyup", this.#keyUpHandler);
-    this.addEventListener("mouseenter", this.#mouseEnterHandler);
-  }
-
-  /** @inheritdoc */
-  override disconnectedCallback(): void {
-    super.disconnectedCallback();
-
-    this.removeEventListener("click", this.#clickHandler);
-    this.removeEventListener("keydown", this.#keyDownHandler);
-    this.removeEventListener("keyup", this.#keyUpHandler);
-    this.removeEventListener("mouseenter", this.#mouseEnterHandler);
-  }
-
-  /** @internal @inheritdoc */
-  protected override _renderContent(): unknown {
-    return html` <div class="icon">
-        <svg class="check" viewBox="0 -960 960 960" aria-hidden="true">
-          <path fill="currentColor" d="M382-240 154-468l57-57 171 171 367-367 57 57-424 424Z" />
-        </svg>
-        <slot name="icon" @slotchange="${this.#handleIconSlotChange}"></slot>
-      </div>
-      <slot></slot>
-      <slot name="trailing-icon" aria-hidden="true" @slotchange="${this.#handleTrailingIconSlotChange}"></slot>`;
-  }
-
-  /** @internal */
-  #handleIconSlotChange(e: Event): void {
-    this.classList.toggle("-with-icon", hasAssignedNodes(<HTMLSlotElement>e.target));
-  }
-
-  /** @internal */
-  #handleTrailingIconSlotChange(e: Event): void {
-    this.classList.toggle("-with-trailing-icon", hasAssignedNodes(<HTMLSlotElement>e.target));
-  }
-
-  /** @internal */
-  #handleClick(e: Event): void {
-    if (!e.defaultPrevented) {
-      this.checked = !this.checked;
-      this.performUpdate();
-
-      if (!this.#spacePressed) {
-        this.menu?.hideAll(true);
-      }
-    }
-  }
-
-  /** @internal */
-  #handleKeyDown(e: KeyboardEvent): void {
-    this.#spacePressed = e.key === " ";
-  }
-
-  /** @internal */
-  #handleKeyUp(): void {
-    this.#spacePressed = false;
-  }
-
-  /** @internal */
-  #handleMouseEnter(): void {
-    this.menu?.items.forEach((item) => {
-      if (item instanceof M3eMenuItemElement && item.submenu?.isOpen) {
-        item.submenu.hide();
-      }
-    });
-  }
-}
-
-declare global {
-  interface HTMLElementTagNameMap {
-    "m3e-menu-item-checkbox": M3eMenuItemCheckboxElement;
-  }
-}

package/src/MenuItemElement.ts

@@ -1,210 +0,0 @@
-import { html } from "lit";
-import { customElement, state } from "lit/decorators.js";
-
-import { hasAssignedNodes, HoverController, LinkButton, Role } from "@m3e/core";
-
-import type { M3eMenuElement } from "./MenuElement";
-import { MenuItemElementBase } from "./MenuItemElementBase";
-import { M3eMenuTriggerElement } from "./MenuTriggerElement";
-
-/**
- * @summary
- * An item of a menu.
- *
- * @description
- * The `m3e-menu-item` component represents a single actionable item within a menu, supporting standard
- * click behavior, optional link semantics, and flexible icon placement for navigation, commands, or
- * contextual actions. It behaves as a button or link depending on its attributes, and can trigger a submenu
- * when a nested `m3e-menu-trigger` is present—enabling hierarchical flows.
- *
- * @example
- * The following example illustrates a basic menu.  The `m3e-menu-trigger` is used to trigger a `m3e-menu` specified
- * by the `for` attribute when its parenting element is activated.
- * ```html
- * <m3e-button>
- *   <m3e-menu-trigger for="menu1">Basic menu</m3e-menu-trigger>
- * </m3e-button>
- * <m3e-menu id="menu1">
- *   <m3e-menu-item>Apple</m3e-menu-item>
- *   <m3e-menu-item>Apricot</m3e-menu-item>
- *   <m3e-menu-item>Avocado</m3e-menu-item>
- *   <m3e-menu-item>Green Apple</m3e-menu-item>
- *   <m3e-menu-item>Green Grapes</m3e-menu-item>
- *   <m3e-menu-item>Olive</m3e-menu-item>
- *   <m3e-menu-item>Orange</m3e-menu-item>
- * </m3e-menu>
- * ```
- *
- * @example
- * The next example illustrates nested menus.  Submenus are triggered by placing a `m3e-menu-trigger` inside a `m3e-menu-item`.
- * ```html
- * <m3e-button>
- *   <m3e-menu-trigger for="menu2">Nested menus</m3e-menu-trigger>
- * </m3e-button>
- * <m3e-menu id="menu2">
- *   <m3e-menu-item>
- *     <m3e-menu-trigger for="menu3">Fruits with A</m3e-menu-trigger>
- *   </m3e-menu-item>
- *   <m3e-menu-item>Grapes</m3e-menu-item>
- *   <m3e-menu-item>Olive</m3e-menu-item>
- *   <m3e-menu-item>Orange</m3e-menu-item>
- * </m3e-menu>
- * <m3e-menu id="menu3">
- *   <m3e-menu-item>Apricot</m3e-menu-item>
- *   <m3e-menu-item>Avocado</m3e-menu-item>
- *   <m3e-menu-item>
- *     <m3e-menu-trigger for="menu4">Apples</m3e-menu-trigger>
- *   </m3e-menu-item>
- * </m3e-menu>
- * <m3e-menu id="menu4">
- *   <m3e-menu-item>Fuji</m3e-menu-item>
- *   <m3e-menu-item>Granny Smith</m3e-menu-item>
- *   <m3e-menu-item>Red Delicious</m3e-menu-item>
- * </m3e-menu>
- * ```
- *
- * @tag m3e-menu-item
- *
- * @slot - Renders the label of the item.
- * @slot icon - Renders an icon before the items's label.
- * @slot trailing-icon - Renders an icon after the item's label.
- *
- * @attr disabled - Whether the element is disabled.
- * @attr download - Whether the `target` of the link button will be downloaded, optionally specifying the new name of the file.
- * @attr href - The URL to which the link button points.
- * @attr rel - The relationship between the `target` of the link button and the document.
- * @attr target - The target of the link button.
- *
- * @cssprop --m3e-menu-item-container-height - Height of the menu item container.
- * @cssprop --m3e-menu-item-color - Text color for unselected, enabled menu items.
- * @cssprop --m3e-menu-item-container-hover-color - State layer hover color for unselected items.
- * @cssprop --m3e-menu-item-container-focus-color - State layer focus color for unselected items.
- * @cssprop --m3e-menu-item-ripple-color - Ripple color for unselected items.
- * @cssprop --m3e-menu-selected-color - Text color for selected or expanded items.
- * @cssprop --m3e-menu-selected-container-color - Background color for selected or expanded items.
- * @cssprop --m3e-menu-item-selected-container-hover-color - State layer hover color for selected items.
- * @cssprop --m3e-menu-item-selected-container-focus-color - State layer focus color for selected items.
- * @cssprop --m3e-menu-item-selected-ripple-color - Ripple color for selected items.
- * @cssprop --m3e-menu-item-disabled-color - Base color for disabled items.
- * @cssprop --m3e-menu-item-disabled-opacity - Opacity percentage for disabled item color mix.
- * @cssprop --m3e-menu-item-icon-label-space - Horizontal gap between icon and content.
- * @cssprop --m3e-menu-item-padding-start - Start padding for the item wrapper.
- * @cssprop --m3e-menu-item-padding-end - End padding for the item wrapper.
- * @cssprop --m3e-menu-item-label-text-font-size - Font size for menu item text.
- * @cssprop --m3e-menu-item-label-text-font-weight - Font weight for menu item text.
- * @cssprop --m3e-menu-item-label-text-line-height - Line height for menu item text.
- * @cssprop --m3e-menu-item-label-text-tracking - Letter spacing for menu item text.
- * @cssprop --m3e-menu-item-focus-ring-shape - Border radius for the focus ring.
- * @cssprop --m3e-menu-item-icon-size - Font size for leading and trailing icons.
- */
-@customElement("m3e-menu-item")
-export class M3eMenuItemElement extends LinkButton(Role(MenuItemElementBase, "menuitem")) {
-  /** @private */ readonly #clickHandler = (e: Event) => this.#handleClick(e);
-  /** @private */ readonly #keyDownHandler = (e: KeyboardEvent) => this.#handleKeyDown(e);
-  /** @private */ readonly #mouseEnterHandler = () => this.#handleMouseEnter();
-
-  /** @private */ @state() private _hasSubmenu = false;
-  /** @private */ #submenuTrigger?: M3eMenuTriggerElement;
-
-  constructor() {
-    super();
-
-    new HoverController(this, {
-      startDelay: 500,
-      endDelay: 500,
-      callback: (hovering) => {
-        if (hovering && !this.disabled && this.#submenuTrigger) {
-          this.#submenuTrigger.menu?.show(this);
-        }
-      },
-    });
-  }
-
-  /** The submenu triggered by the item. */
-  get submenu(): M3eMenuElement | null {
-    return this.#submenuTrigger?.menu ?? null;
-  }
-
-  /** @inheritdoc */
-  override connectedCallback(): void {
-    super.connectedCallback();
-
-    this.addEventListener("click", this.#clickHandler);
-    this.addEventListener("keydown", this.#keyDownHandler);
-    this.addEventListener("mouseenter", this.#mouseEnterHandler);
-  }
-
-  /** @inheritdoc */
-  override disconnectedCallback(): void {
-    super.disconnectedCallback();
-
-    this.removeEventListener("click", this.#clickHandler);
-    this.removeEventListener("keydown", this.#keyDownHandler);
-    this.removeEventListener("mouseenter", this.#mouseEnterHandler);
-  }
-
-  /** @internal @inheritdoc */
-  protected override _renderContent(): unknown {
-    return html`<slot name="icon" aria-hidden="true" @slotchange="${this.#iconSlotChangeHandler}"></slot>
-      <span class="content"><slot @slotchange="${this.#defaultSlotChangeHandler}"></slot></span>
-      ${this._hasSubmenu
-        ? html`<svg class="trailing-icon" aria-hidden="true" viewBox="0 -960 960 960" fill="currentColor">
-            <path d="M400-280v-400l200 200-200 200Z" />
-          </svg>`
-        : html`<slot name="trailing-icon" aria-hidden="true" @slotchange="${this.#trailingIconSlotChangeHandler}">
-          </slot>`}`;
-  }
-
-  /** @private */
-  #defaultSlotChangeHandler(e: Event): void {
-    this.#submenuTrigger = (<HTMLSlotElement>e.target)
-      .assignedElements({ flatten: true })
-      .find((x) => x instanceof M3eMenuTriggerElement);
-    this._hasSubmenu = this.#submenuTrigger !== undefined;
-  }
-
-  /** @private */
-  #iconSlotChangeHandler(e: Event): void {
-    this.classList.toggle("-with-icon", hasAssignedNodes(<HTMLSlotElement>e.target));
-  }
-
-  /** @private */
-  #trailingIconSlotChangeHandler(e: Event): void {
-    this.classList.toggle("-with-trailing-icon", hasAssignedNodes(<HTMLSlotElement>e.target));
-  }
-
-  /** @private */
-  #handleClick(e: Event): void {
-    if (!e.defaultPrevented && !this._hasSubmenu) {
-      this.menu?.hideAll(true);
-    }
-  }
-
-  /** @private */
-  #handleKeyDown(e: KeyboardEvent): void {
-    if (e.defaultPrevented || this.disabled) return;
-
-    switch (e.key) {
-      case "Right":
-      case "ArrowRight":
-        e.preventDefault();
-        this.submenu?.show(this);
-        break;
-    }
-  }
-
-  /** @private */
-  #handleMouseEnter(): void {
-    this.menu?.items.forEach((item) => {
-      if (item instanceof M3eMenuItemElement && item !== this && item.submenu?.isOpen) {
-        item.submenu.hide();
-      }
-    });
-  }
-}
-
-declare global {
-  interface HTMLElementTagNameMap {
-    "m3e-menu-item": M3eMenuItemElement;
-  }
-}

package/src/MenuItemElementBase.ts

@@ -1,158 +0,0 @@
-import { css, CSSResultGroup, html, LitElement, nothing, PropertyValues } from "lit";
-import { query } from "lit/decorators.js";
-
-import {
-  AttachInternals,
-  DesignToken,
-  Disabled,
-  Focusable,
-  isLinkButtonMixin,
-  KeyboardClick,
-  M3eFocusRingElement,
-  M3eRippleElement,
-  M3eStateLayerElement,
-  renderPseudoLink,
-} from "@m3e/core";
-
-import type { M3eMenuElement } from "./MenuElement";
-
-/** A base implementation for an item of a menu. This class must be inherited. */
-export abstract class MenuItemElementBase extends KeyboardClick(
-  Focusable(AttachInternals(Disabled(LitElement), true))
-) {
-  /** The styles of the element. */
-  static override styles: CSSResultGroup = css`
-    :host {
-      display: inline-block;
-      outline: none;
-      user-select: none;
-      flex: none;
-      height: var(--m3e-menu-item-container-height, 3rem);
-    }
-    :host(:not(:focus-visible)) .base {
-      --m3e-state-layer-focus-opacity: 0;
-    }
-    :host(:not(:disabled):not([aria-expanded="true"])) .base {
-      color: var(--m3e-menu-item-color, ${DesignToken.color.onSurface});
-    }
-    :host(:not([aria-expanded="true"])) .base {
-      --m3e-state-layer-hover-color: var(--m3e-menu-item-container-hover-color, ${DesignToken.color.onSurface});
-      --m3e-state-layer-focus-color: var(--m3e-menu-item-container-focus-color, ${DesignToken.color.onSurface});
-      --m3e-ripple-color: var(--m3e-menu-item-ripple-color, ${DesignToken.color.onSurface});
-    }
-    :host(:not(:disabled)[checked]) .base,
-    :host(:not(:disabled)[aria-expanded="true"]) .base {
-      color: var(--m3e-menu-selected-color, ${DesignToken.color.onSecondaryContainer});
-      background-color: var(--m3e-menu-selected-container-color, ${DesignToken.color.secondaryContainer});
-    }
-    :host([checked]) .base,
-    :host([aria-expanded="true"]) .base {
-      --m3e-state-layer-hover-color: var(
-        --m3e-menu-item-selected-container-hover-color,
-        ${DesignToken.color.onSecondaryContainer}
-      );
-      --m3e-state-layer-focus-color: var(
-        --m3e-menu-item-selected-container-focus-color,
-        ${DesignToken.color.onSecondaryContainer}
-      );
-      --m3e-ripple-color: var(--m3e-menu-item-selected-ripple-color, ${DesignToken.color.onSecondaryContainer});
-    }
-    :host(:not(:disabled)) {
-      cursor: pointer;
-    }
-    :host(:disabled) .base {
-      color: color-mix(
-        in srgb,
-        var(--m3e-menu-item-disabled-color, ${DesignToken.color.onSurface}) var(--m3e-menu-item-disabled-opacity, 38%),
-        transparent
-      );
-    }
-    .base {
-      box-sizing: border-box;
-      vertical-align: middle;
-      display: inline-flex;
-      align-items: center;
-      position: relative;
-      width: 100%;
-      height: 100%;
-    }
-    .touch {
-      position: absolute;
-      height: 3rem;
-      left: 0;
-      right: 0;
-    }
-    .wrapper {
-      display: inline-flex;
-      align-items: center;
-      column-gap: var(--m3e-menu-item-icon-label-space, 0.75rem);
-      padding-inline-start: var(--m3e-menu-item-padding-start, 0.75rem);
-      padding-inline-end: var(--m3e-menu-item-padding-end, 0.75rem);
-      font-size: var(--m3e-menu-item-label-text-font-size, ${DesignToken.typescale.standard.label.large.fontSize});
-      font-weight: var(
-        --m3e-menu-item-label-text-font-weight,
-        ${DesignToken.typescale.standard.label.large.fontWeight}
-      );
-      line-height: var(
-        --m3e-menu-item-label-text-line-height,
-        ${DesignToken.typescale.standard.label.large.lineHeight}
-      );
-      letter-spacing: var(--m3e-menu-item-label-text-tracking, ${DesignToken.typescale.standard.label.large.tracking});
-    }
-    .focus-ring {
-      border-radius: var(--m3e-menu-item-focus-ring-shape, ${DesignToken.shape.corner.medium});
-    }
-    .content {
-      flex: 1 1 auto;
-      overflow: hidden;
-      text-overflow: ellipsis;
-      white-space: nowrap;
-    }
-    ::slotted([slot="icon"]),
-    ::slotted([slot="trailing-icon"]),
-    .trailing-icon {
-      flex: none;
-      width: 1em;
-      font-size: var(--m3e-menu-item-icon-size, 1.5rem) !important;
-    }
-    @media (forced-colors: active) {
-      .base {
-        background-color: Menu;
-        color: MenuText;
-      }
-      :host(:disabled) .base {
-        color: GrayText;
-      }
-    }
-  `;
-
-  /** @private */ @query(".focus-ring") private readonly _focusRing?: M3eFocusRingElement;
-  /** @private */ @query(".state-layer") private readonly _stateLayer?: M3eStateLayerElement;
-  /** @private */ @query(".ripple") private readonly _ripple?: M3eRippleElement;
-
-  /** The menu to which this item belongs. */
-  get menu(): M3eMenuElement | null {
-    return this.closest("m3e-menu");
-  }
-
-  /** @inheritdoc */
-  protected override firstUpdated(_changedProperties: PropertyValues<this>): void {
-    super.firstUpdated(_changedProperties);
-    [this._focusRing, this._stateLayer, this._ripple].forEach((x) => x?.attach(this));
-  }
-
-  /** @inheritdoc */
-  override render(): unknown {
-    return html`<div class="base">
-      <m3e-state-layer class="state-layer" ?disabled="${this.disabled}"></m3e-state-layer>
-      <m3e-focus-ring class="focus-ring" inward ?disabled="${this.disabled}"></m3e-focus-ring>
-      <m3e-ripple class="ripple" ?disabled="${this.disabled}"></m3e-ripple>
-      <div class="touch" aria-hidden="true"></div>
-      ${isLinkButtonMixin(this) ? this[renderPseudoLink]() : nothing}
-      <div class="wrapper">${this._renderContent()}</div>
-    </div>`;
-  }
-
-  /** @internal Renders the content of the item. */
-  protected abstract _renderContent(): unknown;
-}

package/src/MenuItemGroupElement.ts

@@ -1,37 +0,0 @@
-import { Role } from "@m3e/core";
-import { css, CSSResultGroup, html, LitElement } from "lit";
-import { customElement } from "lit/decorators.js";
-
-/**
- * @summary
- * Groups related items (such a radios) in a menu.
- *
- * @description
- * The `m3e-menu-item-group` component groups related items within a menu, establishing a shared
- * context for interaction and selection. It enables separation of concerns—such as organizing radio
- * items into mutually exclusive sets.
- *
- * @tag m3e-menu-item-group
- *
- * @slot - Renders the contents of the group.
- */
-@customElement("m3e-menu-item-group")
-export class M3eMenuItemGroupElement extends Role(LitElement, "group") {
-  /** The styles of the element. */
-  static override styles: CSSResultGroup = css`
-    :host {
-      display: contents;
-    }
-  `;
-
-  /** @inheritdoc */
-  protected override render(): unknown {
-    return html`<slot></slot>`;
-  }
-}
-
-declare global {
-  interface HTMLElementTagNameMap {
-    "m3e-menu-item-group": M3eMenuItemGroupElement;
-  }
-}