livewire-material/resources/js/menu.js

/**
 * `materialMenu`: the behaviour of `<x-menu>` — WAI-ARIA's menu button pattern on a popover.
 * `materialSubmenu`: the same pattern one level in, for `<x-menu-item submenu>`.
 *
 * The menu button is the trigger's first button or link. Its ARIA attributes are written by
 * script, which a Livewire morph removes along with anything else the server did not render,
 * so they are written again whenever the trigger is used and after every morph — an open menu
 * lives through one (the popover is keyed), and its button must still say so.
 *
 * The popover hangs on the menu button by CSS anchor positioning. The server can only name the
 * wrapper around the trigger slot, and a trigger taken out of the flow — a `position: fixed` FAB
 * in a corner of the window — leaves that wrapper behind as an empty box where the page put it,
 * so the menu opened there. Script moves the name onto the menu button, beside any name the button
 * carries itself (a button's tooltip anchors on it too), and moves it again after every morph,
 * which puts the server's attributes, and a fresh name, back.
 *
 * A submenu's popover sits inside its parent's, so the browser keeps the two open together — a
 * nested `popover="auto"` light-dismisses only down to its DOM ancestor — and closes the inner one
 * when the outer goes. Its trigger *is* the item, which the server names itself, so the two pieces
 * that exist only for a wrapper (moving the anchor name, and finding the button inside the trigger
 * slot) are overridden away. `items()` stops at the popover it belongs to, so the arrow keys in a
 * menu never walk into an open submenu's rows, nor a submenu's back out into its parent's.
 */
const ITEMS = '[role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"]'

// A popover="auto" closes on the press that lands on its trigger, and the click that follows
// would open it again. A close this recent is taken as that press. It is timed from
// `beforetoggle`, which fires as the popover closes: `toggle` is queued, and arrives after that
// click.
const REOPEN_GUARD_MS = 250

// A submenu opens after the pointer has rested on its item for a moment, and closes a moment after
// it leaves the pair — long enough to cross the gap between them. APG's menu pattern asks for both
// delays. A coarse pointer has no hover to speak of, so there it opens on the press instead.
const HOVER_OPEN_MS = 180
const HOVER_CLOSE_MS = 320

const menu = () => ({
    closedAt: -Infinity,
    anchored: null,
    returnFocus: true,
    focusWasInside: false,
    listeners: [],

    init() {
        const menu = this.$refs.menu

        this.label()
        this.anchor()

        // A morph rewrites the wrapper's style with this render's name and the button's without
        // it, takes the button's ARIA attributes away and gives the popover a new id; the
        // observer runs before the next frame is drawn, so an open menu never moves and its
        // button never shows it shut.
        const observer = new MutationObserver(() => {
            this.anchor()
            this.label()
        })

        observer.observe(this.$refs.trigger, {
            attributes: true,
            attributeFilter: ['style', 'aria-haspopup', 'aria-controls', 'aria-expanded'],
            childList: true,
            subtree: true,
        })
        observer.observe(menu, { attributes: true, attributeFilter: ['id'] })
        this.listeners.push(() => observer.disconnect())

        // Only closes the browser starts — Escape, a press outside — arrive here alone; open()
        // and close() have already done their part, synchronously, because this event is
        // queued and a screen reader or a test reading aria-expanded in between would be told
        // the menu is shut.
        // Whether focus was in the menu is read before it closes: once closed, a browser may
        // already have handed focus to what had it before the menu opened (WebKit does, when
        // that was a focusable region around the trigger).
        this.listen(menu, 'beforetoggle', (event) => {
            this.focusWasInside = event.newState === 'closed' && menu.contains(document.activeElement)

            if (event.newState === 'closed') {
                this.closedAt = performance.now()
            }
        })

        this.listen(menu, 'toggle', (event) => {
            const opened = event.newState === 'open'

            this.control()?.setAttribute('aria-expanded', String(opened))

            if (opened) {
                return
            }

            if (this.returnFocus && (this.focusWasInside || menu.contains(document.activeElement))) {
                this.control()?.focus()
            }

            this.focusWasInside = false
        })

        // A press outside closes the menu without pulling focus back to the trigger.
        this.listen(document, 'pointerdown', (event) => {
            if (!menu.contains(event.target) && !this.$refs.trigger.contains(event.target)) {
                this.returnFocus = false
            }
        })
    },

    control() {
        return this.$refs.trigger.querySelector('button, a[href], [tabindex]')
    },

    /**
     * Moves the anchor name the server gave the wrapper onto the menu button. The wrapper holds a
     * name only as rendered — this render's, which the popover's `position-anchor` matches — so
     * it is read there.
     */
    anchor() {
        const trigger = this.$refs.trigger
        const control = this.control()
        const rendered = trigger.style.getPropertyValue('anchor-name').trim()
        const name = rendered.startsWith('--') ? rendered : this.anchored

        // No menu button, or an engine without anchor positioning: the wrapper keeps the name.
        if (!control || !name) {
            return
        }

        const names = control.style
            .getPropertyValue('anchor-name')
            .split(',')
            .map((each) => each.trim())
            .filter((each) => each.startsWith('--'))

        if (!names.includes(name)) {
            control.style.setProperty('anchor-name', [...names.filter((each) => each !== this.anchored), name].join(', '))
        }

        this.anchored = name

        if (rendered !== '') {
            trigger.style.removeProperty('anchor-name')
        }
    },

    /** Writes only what differs: the observer that calls this watches these same attributes. */
    label() {
        const control = this.control()

        if (!control) {
            return
        }

        const attributes = { 'aria-haspopup': 'menu', 'aria-controls': this.$refs.menu.id, 'aria-expanded': String(this.isOpen()) }

        for (const [name, value] of Object.entries(attributes)) {
            if (control.getAttribute(name) !== value) {
                control.setAttribute(name, value)
            }
        }
    },

    isOpen() {
        return this.$refs.menu.matches(':popover-open')
    },

    open(focus = 'first') {
        this.label()
        this.anchor()

        if (!this.isOpen()) {
            this.$refs.menu.showPopover()
            this.returnFocus = true
        }

        this.control()?.setAttribute('aria-expanded', 'true')

        // `false` opens without taking the focus: a submenu the pointer rested on belongs to the
        // pointer, and taking the focus out from under the keyboard would be the wrong answer.
        if (focus !== false) {
            this.focusItem(focus)
        }
    },

    close() {
        if (this.isOpen()) {
            this.$refs.menu.hidePopover()
        }

        this.control()?.setAttribute('aria-expanded', 'false')
    },

    toggle(focus = 'first') {
        if (this.isOpen()) {
            this.close()
        } else if (performance.now() - this.closedAt > REOPEN_GUARD_MS) {
            this.open(focus)
        }
    },

    /**
     * Every item of *this* menu, disabled ones included: M3 keeps a disabled item focusable
     * ("disabled items can still receive focus, just aren't selectable") so a person reading the
     * menu with the keyboard learns that it exists. activate() is where the refusal lives.
     *
     * An open submenu is a popover of its own nested in this one, and its rows are its: the
     * nearest popover around a row says which menu the arrow keys should find it in.
     */
    items() {
        return [...this.$refs.menu.querySelectorAll(ITEMS)].filter((item) => item.closest('[popover]') === this.$refs.menu)
    },

    /** The menu scrolls when it is too long for the window, so the item taken has to be shown. */
    focusItem(which) {
        const items = this.items()

        this.reach(which === 'last' ? items.at(-1) : items[0])
    },

    reach(item) {
        item?.focus()
        item?.scrollIntoView({ block: 'nearest' })
    },

    navigate(event) {
        const items = this.items()
        const current = items.indexOf(document.activeElement)

        const move = (index) => {
            event.preventDefault()
            this.reach(items[(index + items.length) % items.length])
        }

        switch (event.key) {
            case 'ArrowDown':
                return move(current + 1)
            case 'ArrowUp':
                return move(current < 0 ? items.length - 1 : current - 1)
            case 'Home':
                return move(0)
            case 'End':
                return move(items.length - 1)
            case 'Escape':
                this.returnFocus = true

                return
            case 'Tab':
                this.returnFocus = false
                this.close()

                return
        }

        // Typeahead: a printable letter moves to the next item whose label starts with it.
        if (event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey) {
            const letter = event.key.toLowerCase()
            const ordered = [...items.slice(current + 1), ...items.slice(0, current + 1)]
            const match = ordered.find((item) => item.textContent.trim().toLowerCase().startsWith(letter))

            if (match) {
                event.preventDefault()
                this.reach(match)
            }
        }
    },

    activate(event) {
        const item = event.target.closest(ITEMS)

        if (!item || item.getAttribute('aria-disabled') === 'true' || item.hasAttribute('data-keep-open')) {
            return
        }

        this.close()
    },

    listen(target, type, handler) {
        target.addEventListener(type, handler)
        this.listeners.push(() => target.removeEventListener(type, handler))
    },

    destroy() {
        this.listeners.forEach((remove) => remove())
    },
})

document.addEventListener('alpine:init', () => {
    window.Alpine.data('materialMenu', menu)

    window.Alpine.data('materialSubmenu', () => {
        const base = menu()

        return {
            ...base,
            hoverTimer: null,

            /** The item is the menu button, and the server named it: nothing has to be moved. */
            control() {
                return this.$refs.trigger
            },

            anchor() {},

            navigate(event) {
                // APG: Left closes a submenu and puts the focus back on the item that opened it.
                // Escape does the same through the browser's own light dismiss, which the `toggle`
                // listener follows with the focus.
                if (event.key === 'ArrowLeft') {
                    event.preventDefault()
                    this.returnFocus = true
                    this.close()
                    this.control()?.focus()

                    return
                }

                base.navigate.call(this, event)
            },

            /** Hover opens a submenu only where hovering means something, and never on a first tap. */
            fine(event) {
                return (event === undefined || event.pointerType !== 'touch') && window.matchMedia('(hover: hover) and (pointer: fine)').matches
            },

            hover(event) {
                if (!this.fine(event)) {
                    return
                }

                clearTimeout(this.hoverTimer)
                this.hoverTimer = setTimeout(() => this.open(false), HOVER_OPEN_MS)
            },

            /**
             * The submenu is a DOM child of the item's wrapper, so crossing into it is not a leave;
             * a pointer that really left closes it, unless the keyboard has since taken it over.
             */
            unhover() {
                clearTimeout(this.hoverTimer)

                if (!this.fine()) {
                    return
                }

                this.hoverTimer = setTimeout(() => {
                    if (this.$el.contains(document.activeElement)) {
                        return
                    }

                    this.returnFocus = false
                    this.close()
                }, HOVER_CLOSE_MS)
            },

            destroy() {
                clearTimeout(this.hoverTimer)
                base.destroy.call(this)
            },
        }
    })
})