@material/web

/** * @license * Copyright 2023 Google LLC * SPDX-License-Identifier: Apache-2.0 */ import '../../elevation/elevation.js'; import '../../focus/md-focus-ring.js'; import { LitElement, PropertyValues } from 'lit'; import { MenuItem } from './controllers/menuItemController.js'; import { FocusState } from './controllers/shared.js'; import { Corner, SurfacePositionTarget } from './controllers/surfacePositionController.js'; import { TypeaheadController } from './controllers/typeaheadController.js'; export { Corner } from './controllers/surfacePositionController.js'; /** * The default value for the typeahead buffer time in Milliseconds. */ export declare const DEFAULT_TYPEAHEAD_BUFFER_TIME = 200; /** * @fires opening {Event} Fired before the opening animation begins * @fires opened {Event} Fired once the menu is open, after any animations * @fires closing {Event} Fired before the closing animation begins * @fires closed {Event} Fired once the menu is closed, after any animations */ export declare abstract class Menu extends LitElement { private readonly surfaceEl; private readonly slotEl; /** * The ID of the element in the same root node in which the menu should align * to. Overrides setting `anchorElement = elementReference`. * * __NOTE__: anchor or anchorElement must either be an HTMLElement or resolve * to an HTMLElement in order for menu to open. */ anchor: string; /** * Whether the positioning algorithm should calculate relative to the parent * of the anchor element (`absolute`), relative to the window (`fixed`), or * relative to the document (`document`). `popover` will use the popover API * to render the menu in the top-layer. If your browser does not support the * popover API, it will fall back to `fixed`. * * __Examples for `position = 'fixed'`:__ * * - If there is no `position:relative` in the given parent tree and the * surface is `position:absolute` * - If the surface is `position:fixed` * - If the surface is in the "top layer" * - The anchor and the surface do not share a common `position:relative` * ancestor * * When using `positioning=fixed`, in most cases, the menu should position * itself above most other `position:absolute` or `position:fixed` elements * when placed inside of them. e.g. using a menu inside of an `md-dialog`. * * __NOTE__: Fixed menus will not scroll with the page and will be fixed to * the window instead. * * __Examples for `position = 'document'`:__ * * - There is no parent that creates a relative positioning context e.g. * `position: relative`, `position: absolute`, `transform: translate(x, y)`, * etc. * - You put the effort into hoisting the menu to the top of the DOM like the * end of the `<body>` to render over everything or in a top-layer. * - You are reusing a single `md-menu` element that dynamically renders * content. * * __Examples for `position = 'popover'`:__ * * - Your browser supports `popover`. * - Most cases. Once popover is in browsers, this will become the default. */ positioning: 'absolute' | 'fixed' | 'document' | 'popover'; /** * Skips the opening and closing animations. */ quick: boolean; /** * Displays overflow content like a submenu. Not required in most cases when * using `positioning="popover"`. * * __NOTE__: This may cause adverse effects if you set * `md-menu {max-height:...}` * and have items overflowing items in the "y" direction. */ hasOverflow: boolean; /** * Opens the menu and makes it visible. Alternative to the `.show()` and * `.close()` methods */ open: boolean; /** * Offsets the menu's inline alignment from the anchor by the given number in * pixels. This value is direction aware and will follow the LTR / RTL * direction. * * e.g. LTR: positive -> right, negative -> left * RTL: positive -> left, negative -> right */ xOffset: number; /** * Offsets the menu's block alignment from the anchor by the given number in * pixels. * * e.g. positive -> down, negative -> up */ yOffset: number; /** * Disable the `flip` behavior that usually happens on the horizontal axis * when the surface would render outside the viewport. */ noHorizontalFlip: boolean; /** * Disable the `flip` behavior that usually happens on the vertical axis when * the surface would render outside the viewport. */ noVerticalFlip: boolean; /** * The max time between the keystrokes of the typeahead menu behavior before * it clears the typeahead buffer. */ typeaheadDelay: number; /** * The corner of the anchor which to align the menu in the standard logical * property style of <block>-<inline> e.g. `'end-start'`. * * NOTE: This value may not be respected by the menu positioning algorithm * if the menu would render outisde the viewport. * Use `no-horizontal-flip` or `no-vertical-flip` to force the usage of the value */ anchorCorner: Corner; /** * The corner of the menu which to align the anchor in the standard logical * property style of <block>-<inline> e.g. `'start-start'`. * * NOTE: This value may not be respected by the menu positioning algorithm * if the menu would render outisde the viewport. * Use `no-horizontal-flip` or `no-vertical-flip` to force the usage of the value */ menuCorner: Corner; /** * Keeps the user clicks outside the menu. * * NOTE: clicking outside may still cause focusout to close the menu so see * `stayOpenOnFocusout`. */ stayOpenOnOutsideClick: boolean; /** * Keeps the menu open when focus leaves the menu's composed subtree. * * NOTE: Focusout behavior will stop propagation of the focusout event. Set * this property to true to opt-out of menu's focusout handling altogether. */ stayOpenOnFocusout: boolean; /** * After closing, does not restore focus to the last focused element before * the menu was opened. */ skipRestoreFocus: boolean; /** * The element that should be focused by default once opened. * * NOTE: When setting default focus to 'LIST_ROOT', remember to change * `tabindex` to `0` and change md-menu's display to something other than * `display: contents` when necessary. */ defaultFocus: FocusState; /** * Turns off navigation wrapping. By default, navigating past the end of the * menu items will wrap focus back to the beginning and vice versa. Use this * for ARIA patterns that do not wrap focus, like combobox. */ noNavigationWrap: boolean; protected slotItems: HTMLElement[]; private typeaheadActive; /** * Whether or not the current menu is a submenu and should not handle specific * navigation keys. * * @export */ isSubmenu: boolean; /** * The event path of the last window pointerdown event. */ private pointerPath; /** * Whether or not the menu is repositoining due to window / document resize */ private isRepositioning; private readonly openCloseAnimationSignal; private readonly listController; /** * Whether the menu is animating upwards or downwards when opening. This is * helpful for calculating some animation calculations. */ private get openDirection(); /** * The element that was focused before the menu opened. */ private lastFocusedElement; /** * Handles typeahead navigation through the menu. */ typeaheadController: TypeaheadController; private currentAnchorElement; /** * The element which the menu should align to. If `anchor` is set to a * non-empty idref string, then `anchorEl` will resolve to the element with * the given id in the same root node. Otherwise, `null`. */ get anchorElement(): (HTMLElement & Partial<SurfacePositionTarget>) | null; set anchorElement(element: (HTMLElement & Partial<SurfacePositionTarget>) | null); private readonly internals; constructor(); /** * Handles positioning the surface and aligning it to the anchor as well as * keeping it in the viewport. */ private readonly menuPositionController; /** * The menu items associated with this menu. The items must be `MenuItem`s and * have both the `md-menu-item` and `md-list-item` attributes. */ get items(): MenuItem[]; protected willUpdate(changed: PropertyValues<Menu>): void; update(changed: PropertyValues<Menu>): void; private readonly onWindowResize; connectedCallback(): void; disconnectedCallback(): void; getBoundingClientRect(): DOMRect; getClientRects(): DOMRectList; protected render(): import("lit-html").TemplateResult<1>; /** * Renders the positionable surface element and its contents. */ private renderSurface; /** * Renders the menu items' slot */ private renderMenuItems; /** * Renders the elevation component. */ private renderElevation; private getSurfaceClasses; private readonly handleFocusout; private captureKeydown; /** * Saves the last focused element focuses the new element based on * `defaultFocus`, and animates open. */ private readonly onOpened; /** * Animates closed. */ private readonly beforeClose; /** * Focuses the last focused element. */ private readonly onClosed; /** * Performs the opening animation: * * https://direct.googleplex.com/#/spec/295000003+271060003 * * @return A promise that resolve to `true` if the animation was aborted, * `false` if it was not aborted. */ private animateOpen; /** * Performs the closing animation: * * https://direct.googleplex.com/#/spec/295000003+271060003 */ private animateClose; private handleKeydown; private setUpGlobalEventListeners; private cleanUpGlobalEventListeners; private readonly onWindowPointerdown; /** * We cannot listen to window click because Safari on iOS will not bubble a * click event on window if the item clicked is not a "clickable" item such as * <body> */ private readonly onDocumentClick; private onCloseMenu; private onDeactivateItems; private onRequestActivation; private handleDeactivateTypeahead; private handleActivateTypeahead; private handleStayOpenOnFocusout; private handleCloseOnFocusout; close(): void; show(): void; /** * Activates the next item in the menu. If at the end of the menu, the first * item will be activated. * * @return The activated menu item or `null` if there are no items. */ activateNextItem(): MenuItem; /** * Activates the previous item in the menu. If at the start of the menu, the * last item will be activated. * * @return The activated menu item or `null` if there are no items. */ activatePreviousItem(): MenuItem; /** * Repositions the menu if it is open. * * Useful for the case where document or window-positioned menus have their * anchors moved while open. */ reposition(): void; }