@fabric-msft/fabric-web 5.0.1 → 7.0.0

package/esm/components/menu/menu.js

@@ -0,0 +1,698 @@
+import { attr, observable, FASTElement, Updates } from '@microsoft/fast-element';
+import { keyEnter, keySpace, keyEscape } from '@microsoft/fast-web-utilities';
+import { MenuItem } from '../menu-item/menu-item.js';
+import { MenuList } from '../menu-list/menu-list.js';
+import { MenuPositions, MenuRepositionModes } from './menu.options.js';
+import { MenuPositioning } from './menu.positioning.js';
+import { createUniqueId } from '../../util/hash-utilities.js';
+
+var __decorate = globalThis && globalThis.__decorate || function (decorators, target, key, desc) {
+  var c = arguments.length,
+    r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc,
+    d;
+  if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+  return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+/**
+ * Menu
+ * @summary A Menu component that provides an interactive menu interface with support for various trigger and open behaviors.
+ *
+ * When `reposition-mode="auto"` is set the component creates a {@link MenuPositioning} manager backed by
+ * `FlexiblePositionStrategy`. On every open/resize/scroll cycle the strategy measures available space, picks
+ * the best-fitting position from the preferred position plus its fallbacks, and resizes the menu if there is
+ * not enough available space. When `reposition-mode="none"` (default) the same strategy positions the menu
+ * once on open but does not reposition on resize or scroll. Supply `overflowBoundary` to scope collision
+ * detection to a specific scrolling container instead of the viewport.
+ *
+ * @example
+ * ```html
+ * <fabric-menu open-on-hover="true" open-on-context="true" close-on-scroll="true" persist-on-item-click="true">
+ *   <div slot="trigger">Menu Trigger</div>
+ *   <ul>
+ *     <li>Menu Item 1</li>
+ *     <li>Menu Item 2</li>
+ *     <li>Menu Item 3</li>
+ *   </ul>
+ * </fabric-menu>
+ * ```
+ *
+ * @attr {boolean | undefined} open-on-hover - Determines if the menu should open on hover.
+ * @attr {boolean | undefined} open-on-context - Determines if the menu should open on right click.
+ * @attr {boolean | undefined} close-on-scroll - Determines if the menu should close on scroll.
+ * @attr {boolean | undefined} persist-on-item-click - Determines if the menu open state should persist on click of a menu item.
+ * @attr {boolean | undefined} split - Determines if the menu is in split state (for split button pattern).
+ * @attr {MenuPosition | undefined} menu-position - Determines whether the menu list is above or below the trigger. Defaults to `"below"`.
+ * @attr {MenuRepositionMode | undefined} reposition-mode - Controls JS-based repositioning. `"auto"` enables
+ *   `FlexiblePositionStrategy` which detects collisions and flips the menu to the best-fitting position on
+ *   every resize/scroll cycle. `"none"` (default) disables JS repositioning and relies on CSS anchored positioning.
+ *
+ * @prop {boolean | undefined} openOnHover - Determines if the menu should open on hover.
+ * @prop {boolean | undefined} openOnContext - Determines if the menu should open on right click.
+ * @prop {boolean | undefined} closeOnScroll - Determines if the menu should close on scroll.
+ * @prop {boolean | undefined} persistOnItemClick - Determines if the menu open state should persist on click of a menu item.
+ * @prop {boolean | undefined} split - Determines if the menu is in split state.
+ * @prop {MenuList[]} slottedMenuList - Holds the slotted menu list.
+ * @prop {HTMLElement[]} slottedTriggers - Holds the slotted triggers.
+ * @prop {MenuPosition | undefined} menuPosition - Reflects the active resolved position (`"above"` or `"below"`). May
+ *   differ from the authored `menu-position` attribute when `reposition-mode="auto"` has flipped the menu.
+ * @prop {MenuRepositionMode | undefined} repositionMode - The active repositioning mode (`"auto"` | `"none"`).
+ * @prop {HTMLElement | undefined} overflowBoundary - An optional scrolling container used by the
+ *   `FlexiblePositionStrategy` as the collision boundary instead of the viewport. Only relevant when
+ *   `reposition-mode="auto"`.
+ *
+ * @slot primary-action - Slot for the primary action element (used when split is true).
+ * @slot trigger - Slot for the trigger element.
+ * @slot - Default slot for the menu list.
+ *
+ * @csspart trigger - Represents the trigger element of the menu.
+ * @csspart menu-list - Represents the menu list element.
+ *
+ * @method toggleMenu - Toggles the open state of the menu.
+ * @method closeMenu - Closes the menu.
+ * @method openMenu - Opens the menu.
+ * @method focusMenuList - Focuses on the menu list.
+ * @method focusTrigger - Focuses on the menu trigger.
+ * @method menuKeydownHandler - Handles keyboard interaction for the menu.
+ * @method triggerKeydownHandler - Handles keyboard interaction for the trigger.
+ *
+ * @fires toggle - Event fired when the menu is toggled.
+ * @fires change - Event fired when the state of a menu item changes.
+ *
+ * @extends FASTElement
+ * @tagname fabric-menu
+ * @public
+ */
+class Menu extends FASTElement {
+  constructor() {
+    super(...arguments);
+    /**
+     * The positioning instance for the menu.
+     * @private
+     */
+    this.positioning = null;
+    /**
+     * Determines if the menu should open on hover.
+     * @public
+     */
+    this.openOnHover = false;
+    /**
+     * Determines if the menu should open on right click.
+     * @public
+     */
+    this.openOnContext = false;
+    /**
+     * Determines if the menu should close on scroll.
+     * @public
+     */
+    this.closeOnScroll = false;
+    /**
+     * Determines if the menu open state should persis on click of menu item
+     * @public
+     */
+    this.persistOnItemClick = false;
+    /**
+     * Determines if the menu is in split state (for split button pattern).
+     * @public
+     */
+    this.split = false;
+    /**
+     * Determines whether the menu list is above or below the trigger.
+     * @public
+     */
+    this.menuPosition = MenuPositions.below;
+    /**
+     * The mode for repositioning the menu when it overflows the boundary.
+     *
+     * Both modes render the menu list on the top layer via the popover API.
+     *
+     * - `"none"` (default) — uses CSS anchor positioning to keep the popover
+     *   attached to the trigger. No JS scroll/resize listeners are added.
+     *   The menu will not flip or resize to avoid overflow.
+     * - `"auto"` — uses `FlexiblePositionStrategy` for JS-based positioning.
+     *   On every resize and scroll event the strategy measures available space,
+     *   picks the best-fitting position from the preferred position plus its
+     *   fallbacks, and resizes the menu if there is not enough available space.
+     *
+     * @public
+     * @default "none"
+     */
+    this.repositionMode = MenuRepositionModes.none;
+    /**
+     * Holds the slotted menu list.
+     * @public
+     */
+    this.slottedMenuList = [];
+    /**
+     * Holds the slotted triggers.
+     * @public
+     */
+    this.slottedTriggers = [];
+    /**
+     * Defines whether the menu is open or not.
+     * @internal
+     */
+    this._open = false;
+    /**
+     * Auto-generated CSS anchor name for tying the popover to the trigger
+     * via CSS anchor positioning when `reposition-mode="none"`.
+     * @internal
+     */
+    this._anchorName = `--${createUniqueId("menu-anchor-")}`;
+    /**
+     * Internal open handler used by multiple entry points.
+     * @private
+     */
+    this.openMenuInternal = e => {
+      if (this._open) {
+        return;
+      }
+      if (this.repositionMode === MenuRepositionModes.auto) {
+        this.createPositioningManager();
+        this.scheduleReposition();
+        this.addRepositioningHandlers();
+      }
+      this.setMenuOpenState(true);
+      this.focusMenuList();
+      if (e && this.openOnContext) {
+        e.preventDefault();
+      }
+      document.addEventListener("click", this.documentClickHandler);
+      if (this.closeOnScroll) {
+        document.addEventListener("scroll", this.closeMenu);
+      }
+    };
+    /**
+     * Internal close handler used by multiple entry points.
+     * @private
+     */
+    this.closeMenuInternal = () => {
+      var _a;
+      if (!this._open) {
+        return;
+      }
+      // Close any open submenu popovers before hiding the menu list
+      if (this._menuList instanceof MenuList && this._menuList.menuItems) {
+        for (const item of this._menuList.menuItems) {
+          if (item instanceof MenuItem) {
+            try {
+              (_a = item.submenu) === null || _a === void 0 ? void 0 : _a.hidePopover();
+            } catch {
+              /* already closed */
+            }
+          }
+        }
+      }
+      this.setMenuOpenState(false);
+      this.removeRepositioningListeners();
+      document.removeEventListener("click", this.documentClickHandler);
+      if (this.closeOnScroll) {
+        document.removeEventListener("scroll", this.closeMenu);
+      }
+    };
+    /**
+     * Delegates resize + flip logic to the positioning strategy.
+     * @private
+     */
+    this.repositionMenu = () => {
+      var _a;
+      if (!this.positioning || !this._menuList) {
+        return;
+      }
+      this.positioning.position = (_a = this.menuPosition) !== null && _a !== void 0 ? _a : MenuPositions.below;
+      this.positioning.reposition();
+    };
+    /**
+     * Handler for window resize/scroll changes.
+     * Called synchronously so the menu tracks the trigger without a frame of lag.
+     * @private
+     */
+    this.handleWindowChanges = () => {
+      if (!this._open) {
+        return;
+      }
+      this.repositionMenu();
+    };
+    /**
+     * Toggles the open state of the menu.
+     * @public
+     */
+    this.toggleMenu = () => {
+      this.setComponent();
+      if (this._open) {
+        this.closeMenuInternal();
+        this.focusTrigger();
+      } else {
+        this.openMenuInternal();
+      }
+    };
+    /**
+     * Closes the menu.
+     * @public
+     */
+    this.closeMenu = () => {
+      this.closeMenuInternal();
+    };
+    /**
+     * Opens the menu.
+     * @public
+     */
+    this.openMenu = e => {
+      this.openMenuInternal(e);
+    };
+    /**
+     * Handles keyboard interaction for the trigger. Toggles the menu when the Space or Enter key is pressed.
+     *
+     * @param e - the keyboard event
+     * @public
+     */
+    this.triggerKeydownHandler = e => {
+      if (e.defaultPrevented) {
+        return;
+      }
+      const key = e.key;
+      switch (key) {
+        case keySpace:
+        case keyEnter:
+          e.preventDefault();
+          this.toggleMenu();
+          break;
+        default:
+          return true;
+      }
+    };
+    /**
+     * Handles document click events to close the menu when clicking outside (light dismiss).
+     * @internal
+     * @param e - The event triggered on document click.
+     */
+    this.documentClickHandler = e => {
+      if (!this._open) {
+        return;
+      }
+      if (!e.composedPath().some(el => el === this._trigger || el === this._menuList)) {
+        this.closeMenu();
+      }
+    };
+  }
+  /**
+   * Handles changes to the menuPosition attribute.
+   * Updates the positioning strategy and triggers a reposition if
+   * the menu is currently open, without mutating the public attribute.
+   * @public
+   */
+  menuPositionChanged() {
+    var _a;
+    if (this.positioning) {
+      this.positioning.position = (_a = this.menuPosition) !== null && _a !== void 0 ? _a : MenuPositions.below;
+    }
+    if (this._open) {
+      this.scheduleReposition();
+    }
+  }
+  /**
+   * Handles menu list slot changes.
+   * @internal
+   */
+  slottedMenuListChanged() {
+    this.setComponent();
+    if (this._open) {
+      this.scheduleReposition();
+    }
+  }
+  /**
+   * Handles trigger slot changes.
+   * @internal
+   */
+  slottedTriggersChanged() {
+    this.setComponent();
+    if (this._open) {
+      this.scheduleReposition();
+    }
+  }
+  /**
+   * Updates menu list open state and ARIA expanded.
+   * @private
+   */
+  setMenuOpenState(isOpen) {
+    var _a;
+    this._open = isOpen;
+    (_a = this._trigger) === null || _a === void 0 ? void 0 : _a.setAttribute("aria-expanded", `${isOpen}`);
+    if (this._menuList) {
+      this._menuList.classList.toggle("menu-open", isOpen);
+      try {
+        if (isOpen) {
+          this._menuList.showPopover();
+        } else {
+          this._menuList.hidePopover();
+        }
+      } catch {
+        // Ignore if popover state already matches
+      }
+    }
+  }
+  /**
+   * Schedules a reposition on the next microtask.
+   * @private
+   */
+  scheduleReposition() {
+    Updates.enqueue(() => {
+      this.repositionMenu();
+    });
+  }
+  /**
+   * Adds window event listeners.
+   * @private
+   */
+  addWindowEventListeners() {
+    window.addEventListener("resize", this.handleWindowChanges);
+    window.addEventListener("scroll", this.handleWindowChanges, {
+      passive: true
+    });
+  }
+  /**
+   * Removes window event listeners.
+   * @private
+   */
+  removeWindowEventListeners() {
+    window.removeEventListener("resize", this.handleWindowChanges);
+    window.removeEventListener("scroll", this.handleWindowChanges);
+  }
+  /**
+   * Adds overflow boundary event listeners.
+   * @private
+   */
+  addOverflowBoundaryEventListeners() {
+    if (this.overflowBoundary) {
+      this.overflowBoundary.addEventListener("scroll", this.handleWindowChanges, {
+        passive: true
+      });
+    }
+  }
+  /**
+   * Adds repositioning handlers.
+   * @private
+   */
+  addRepositioningHandlers() {
+    this.addWindowEventListeners();
+    this.addOverflowBoundaryEventListeners();
+  }
+  /**
+   * Creates the positioning manager.
+   * @private
+   */
+  createPositioningManager() {
+    if (this._menuList && this._trigger) {
+      this.positioning = null;
+      this.positioning = new MenuPositioning({
+        menuReference: this._menuList,
+        anchorReference: this._trigger,
+        overflowBoundaryReference: this.overflowBoundary
+      });
+    }
+  }
+  /**
+   * Clears inline position styles written by JS positioning so that
+   * CSS anchor positioning rules can take effect.
+   * @private
+   */
+  clearInlinePositionStyles() {
+    if (this._menuList) {
+      const s = this._menuList.style;
+      s.left = "";
+      s.right = "";
+      s.top = "";
+      s.bottom = "";
+      s.maxHeight = "";
+      s.overflow = "";
+    }
+  }
+  /**
+   * Removes repositioning event listeners.
+   * @private
+   */
+  removeRepositioningListeners() {
+    if (this._menuList) {
+      this.removeWindowEventListeners();
+    }
+    if (this.overflowBoundary) {
+      this.overflowBoundary.removeEventListener("scroll", this.handleWindowChanges);
+    }
+  }
+  /**
+   * Called when the element is connected to the DOM.
+   * @public
+   */
+  connectedCallback() {
+    super.connectedCallback();
+    Updates.enqueue(() => {
+      this.setComponent();
+    });
+  }
+  /**
+   * Called when the element is disconnected from the DOM.
+   * @public
+   */
+  disconnectedCallback() {
+    super.disconnectedCallback();
+    this.removeListeners();
+    this.removeRepositioningListeners();
+    document.removeEventListener("click", this.documentClickHandler);
+    document.removeEventListener("scroll", this.closeMenu);
+  }
+  /**
+   * Sets the component.
+   * @public
+   */
+  setComponent() {
+    if (this.$fastController.isConnected && this.slottedMenuList.length && this.slottedTriggers.length) {
+      this._trigger = this.slottedTriggers[0];
+      this._menuList = this.slottedMenuList[0];
+      this._trigger.setAttribute("aria-haspopup", "true");
+      this._trigger.setAttribute("aria-expanded", `${this._open}`);
+      this._menuList.setAttribute("data-menu-list", "");
+      this._menuList.setAttribute("popover", "manual");
+      // Preserve any existing anchor-name values (e.g. set by a fabric-tooltip)
+      // so the trigger can serve as a CSS anchor for multiple positioned elements.
+      const existingAnchorName = this._trigger.style.getPropertyValue("anchor-name");
+      this._trigger.style.anchorName = existingAnchorName ? `${existingAnchorName}, ${this._anchorName}` : this._anchorName;
+      this._menuList.style.positionAnchor = this._anchorName;
+      this.addListeners();
+    }
+  }
+  /**
+   * Focuses on the menu list.
+   * @public
+   */
+  focusMenuList() {
+    Updates.enqueue(() => {
+      const list = this._menuList;
+      list.focus();
+    });
+  }
+  /**
+   * Focuses on the menu trigger.
+   * @public
+   */
+  focusTrigger() {
+    Updates.enqueue(() => {
+      this._trigger.focus();
+    });
+  }
+  /**
+   * Called whenever the 'openOnHover' property changes.
+   *
+   * @param oldValue - The previous value of 'openOnHover'.
+   * @param newValue - The new value of 'openOnHover'.
+   * @public
+   */
+  openOnHoverChanged(_oldValue, newValue) {
+    var _a, _b;
+    if (newValue) {
+      (_a = this._trigger) === null || _a === void 0 ? void 0 : _a.addEventListener("mouseover", this.openMenu);
+    } else {
+      (_b = this._trigger) === null || _b === void 0 ? void 0 : _b.removeEventListener("mouseover", this.openMenu);
+    }
+  }
+  /**
+   * Called whenever the 'persistOnItemClick' property changes.
+   *
+   * @public
+   * @param oldValue - The previous value of 'persistOnItemClick'.
+   * @param newValue - The new value of 'persistOnItemClick'.
+   */
+  persistOnItemClickChanged(_oldValue, newValue) {
+    var _a, _b;
+    if (!newValue) {
+      (_a = this._menuList) === null || _a === void 0 ? void 0 : _a.addEventListener("change", this.closeMenu);
+    } else {
+      (_b = this._menuList) === null || _b === void 0 ? void 0 : _b.removeEventListener("change", this.closeMenu);
+    }
+  }
+  /**
+   * Called whenever the 'repositionMode' property changes.
+   *
+   * @public
+   * @param oldValue - The previous value of 'repositionMode'.
+   * @param newValue - The new value of 'repositionMode'.
+   */
+  repositionModeChanged(_oldValue, newValue) {
+    if (this._open) {
+      if (newValue === MenuRepositionModes.auto) {
+        if (!this.positioning) {
+          this.createPositioningManager();
+        }
+        this.addRepositioningHandlers();
+        this.scheduleReposition();
+      } else {
+        this.removeRepositioningListeners();
+        this.clearInlinePositionStyles();
+      }
+    }
+  }
+  /**
+   * Called whenever the 'overflowBoundary' property changes.
+   *
+   * @public
+   */
+  overflowBoundaryChanged(oldValue, newValue) {
+    var _a;
+    if (oldValue) {
+      oldValue.removeEventListener("scroll", this.handleWindowChanges);
+    }
+    if (this._open) {
+      if (newValue) {
+        newValue.addEventListener("scroll", this.handleWindowChanges, {
+          passive: true
+        });
+      }
+      (_a = this.positioning) === null || _a === void 0 ? void 0 : _a.setOverflowBoundaryReference(newValue !== null && newValue !== void 0 ? newValue : null);
+      this.scheduleReposition();
+    } else if (this.positioning) {
+      this.positioning.setOverflowBoundaryReference(newValue !== null && newValue !== void 0 ? newValue : null);
+    }
+  }
+  /**
+   * Called whenever the 'openOnContext' property changes.
+   *
+   * @public
+   * @param oldValue - The previous value of 'openOnContext'.
+   * @param newValue - The new value of 'openOnContext'.
+   */
+  openOnContextChanged(_oldValue, newValue) {
+    var _a, _b;
+    if (newValue) {
+      (_a = this._trigger) === null || _a === void 0 ? void 0 : _a.addEventListener("contextmenu", this.openMenu);
+    } else {
+      (_b = this._trigger) === null || _b === void 0 ? void 0 : _b.removeEventListener("contextmenu", this.openMenu);
+    }
+  }
+  /**
+   * Called whenever the 'closeOnScroll' property changes.
+   *
+   * @public
+   * @param oldValue - The previous value of 'closeOnScroll'.
+   * @param newValue - The new value of 'closeOnScroll'.
+   */
+  closeOnScrollChanged(_oldValue, newValue) {
+    if (!this._open) {
+      return;
+    }
+    if (newValue) {
+      document.addEventListener("scroll", this.closeMenu);
+    } else {
+      document.removeEventListener("scroll", this.closeMenu);
+    }
+  }
+  /**
+   * Adds event listeners.
+   *
+   * @internal
+   */
+  addListeners() {
+    var _a, _b, _c, _d, _e;
+    (_a = this._trigger) === null || _a === void 0 ? void 0 : _a.addEventListener("keydown", this.triggerKeydownHandler);
+    if (!this.persistOnItemClick) {
+      (_b = this._menuList) === null || _b === void 0 ? void 0 : _b.addEventListener("change", this.closeMenu);
+    }
+    if (this.openOnHover) {
+      (_c = this._trigger) === null || _c === void 0 ? void 0 : _c.addEventListener("mouseover", this.openMenu);
+    } else if (this.openOnContext) {
+      (_d = this._trigger) === null || _d === void 0 ? void 0 : _d.addEventListener("contextmenu", this.openMenu);
+    } else {
+      (_e = this._trigger) === null || _e === void 0 ? void 0 : _e.addEventListener("click", this.toggleMenu);
+    }
+  }
+  /**
+   * Removes event listeners.
+   *
+   * @internal
+   */
+  removeListeners() {
+    var _a, _b, _c, _d, _e;
+    (_a = this._trigger) === null || _a === void 0 ? void 0 : _a.removeEventListener("keydown", this.triggerKeydownHandler);
+    if (!this.persistOnItemClick) {
+      (_b = this._menuList) === null || _b === void 0 ? void 0 : _b.removeEventListener("change", this.closeMenu);
+    }
+    if (this.openOnHover) {
+      (_c = this._trigger) === null || _c === void 0 ? void 0 : _c.removeEventListener("mouseover", this.openMenu);
+    }
+    if (this.openOnContext) {
+      (_d = this._trigger) === null || _d === void 0 ? void 0 : _d.removeEventListener("contextmenu", this.openMenu);
+    } else {
+      (_e = this._trigger) === null || _e === void 0 ? void 0 : _e.removeEventListener("click", this.toggleMenu);
+    }
+  }
+  /**
+   * Handles keyboard interaction for the menu. Closes the menu and focuses on the trigger when the Escape key is pressed.
+   *
+   * @param e - the keyboard event
+   * @public
+   */
+  menuKeydownHandler(e) {
+    if (e.defaultPrevented) {
+      return;
+    }
+    const key = e.key;
+    switch (key) {
+      case keyEscape:
+        e.preventDefault();
+        if (this._open) {
+          this.closeMenuInternal();
+          this.focusTrigger();
+        }
+        break;
+      default:
+        return true;
+    }
+  }
+}
+__decorate([attr({
+  attribute: "open-on-hover",
+  mode: "boolean"
+})], Menu.prototype, "openOnHover", void 0);
+__decorate([attr({
+  attribute: "open-on-context",
+  mode: "boolean"
+})], Menu.prototype, "openOnContext", void 0);
+__decorate([attr({
+  attribute: "close-on-scroll",
+  mode: "boolean"
+})], Menu.prototype, "closeOnScroll", void 0);
+__decorate([attr({
+  attribute: "persist-on-item-click",
+  mode: "boolean"
+})], Menu.prototype, "persistOnItemClick", void 0);
+__decorate([attr({
+  mode: "boolean"
+})], Menu.prototype, "split", void 0);
+__decorate([attr({
+  attribute: "menu-position"
+})], Menu.prototype, "menuPosition", void 0);
+__decorate([attr({
+  attribute: "reposition-mode"
+})], Menu.prototype, "repositionMode", void 0);
+__decorate([observable], Menu.prototype, "overflowBoundary", void 0);
+__decorate([observable], Menu.prototype, "slottedMenuList", void 0);
+__decorate([observable], Menu.prototype, "slottedTriggers", void 0);
+
+export { Menu };