Popover Blade component for Laravel and Livewire

@props([
    // The trigger button's id; scripts open the popover by it (popover.open('{id}')), so it must be unique. Made up when
    // left out.
    'id' => null,
    // Text for a button with a chevron, or a trigger slot with your own markup. Without either, the trigger is an
    // icon-only button.
    'trigger' => null,
    // The trigger's name for screen readers. Required for the icon-only trigger.
    'label' => null,
    // The icon-only trigger's icon.
    'icon' => 'info',
    // The trigger's look, as on the button: primary, secondary, tertiary, danger, neutral or link.
    'variant' => 'neutral',
    // The trigger's size: sm, md or lg.
    'size' => 'md',
    // A heading at the top of the panel, which also names it for screen readers. Without one, the trigger names it.
    'title' => null,
    // How wide the panel is: sm, md or lg.
    'width' => 'md',
    // Which edge of the trigger the panel lines up with: start (left in left-to-right pages), center or end.
    'align' => 'start',
])

@php
    // A typo fails loudly, naming the values that work, instead of quietly rendering something else.
    if (! in_array($align, ['start', 'center', 'end'], true)) {
        throw new \InvalidArgumentException("Unknown align [{$align}] for <x-widget.popover>. Use one of: start, center, end.");
    }
    $widths = ['sm' => 'w-64', 'md' => 'w-80', 'lg' => 'w-96'];
    if (! array_key_exists($width, $widths)) {
        throw new \InvalidArgumentException("Unknown width [{$width}] for <x-widget.popover>. Use one of: sm, md, lg.");
    }
    // The trigger's look, passed to the button; checked here too, so the error names the tag that was written.
    if (! in_array($variant, ['primary', 'secondary', 'tertiary', 'danger', 'neutral', 'link'], true)) {
        throw new \InvalidArgumentException("Unknown variant [{$variant}] for <x-widget.popover>. Use one of: primary, secondary, tertiary, danger, neutral, link.");
    }
    // Scripts open it by the trigger's id, so an explicit id must be unique; a derived one gets a suffix.
    $id = app(\App\View\Widget\ElementIds::class)->claim($id ?? 'popover', explicit: $id !== null);
    $panelId = "{$id}-panel";
    $custom = $trigger instanceof \Illuminate\View\ComponentSlot;
    $triggerAttributes = new \Illuminate\View\ComponentAttributeBag([
        'id' => $id,
        'popovertarget' => $panelId,
        'aria-haspopup' => 'dialog',
        'aria-expanded' => 'false',
        'aria-controls' => $panelId,
        'data-popover-trigger' => '',
        // The script keeps aria-expanded in step with the panel; a Livewire render would put back the server's "false".
        'wire:ignore.self' => '',
    ]);
@endphp

{{--
    A panel of anything (text, a form, links) beside a button, on the native popover: the browser opens it from
    popovertarget and closes it on Esc or a click outside, and it sits in the top layer, so a table's overflow or a modal
    can't clip it. resources/js/widget/popover places it, moves focus into it and back, and closes it when focus leaves.
    A non-modal dialog: the page stays usable behind it. For a menu of actions, see the dropdown.
--}}
<div data-popover data-no-row-click data-align="{{ $align }}" {{ $attributes->class(['relative inline-flex']) }}>
    @if ($custom)
        {{-- It is one button, so keep links and other buttons out of the slot. --}}
        <button
            type="button"
            @if ($label) aria-label="{{ $label }}" @endif
            {{ $trigger->attributes->class(['focus-visible:ring-primary inline-flex items-center gap-2 rounded-xl text-start outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-offset-surface'])->merge($triggerAttributes->getAttributes()) }}
        >{{ $trigger }}</button>
    @elseif (is_string($trigger) && $trigger !== '')
        <x-widget.button :variant="$variant" :size="$size" icon-end="chevron-down" :attributes="$triggerAttributes">{{ $trigger }}</x-widget.button>
    @else
        <x-widget.button :variant="$variant" :size="$size" :icon="$icon" :label="$label" :attributes="$triggerAttributes" />
    @endif

    <div
        id="{{ $panelId }}"
        popover
        role="dialog"
        tabindex="-1"
        {{-- The script places the open panel (inline top/left, data-side); a Livewire render would wipe that and it would
             jump. What's inside still updates. --}}
        wire:ignore.self
        @if ($title) aria-labelledby="{{ $panelId }}-title" @else aria-labelledby="{{ $id }}" @endif
        data-popover-panel
        @class([
            // hidden until open: a display utility on a popover beats the browser's own rule that hides it while closed.
            'border-line bg-surface text-foreground fixed inset-auto m-0 hidden max-h-[min(32rem,calc(100dvh-2rem))] max-w-[calc(100vw-1rem)] flex-col overflow-y-auto overscroll-contain rounded-2xl border p-4 text-sm shadow-lg outline-none open:flex',
            $widths[$width],
            // Fades and grows in from the trigger's side (data-side, set by the script when it flips above).
            'origin-top opacity-0 scale-95 transition-[opacity,scale,display,overlay] transition-discrete duration-150 open:opacity-100 open:scale-100 starting:open:opacity-0 starting:open:scale-95 data-[side=top]:origin-bottom motion-reduce:transition-none',
        ])
    >
        @if ($title)
            <h2 id="{{ $panelId }}-title" class="text-foreground mb-2 text-base font-semibold">{{ $title }}</h2>
        @endif
        {{ $slot }}
    </div>
</div><?php /* No newline after this: PHP drops it after a closing tag, so no space trails the component in running text. */ ?>

// Drives <x-widget.popover>. Opening, Esc and click-outside come from the native popover (popovertarget); this places
// the panel beside its trigger (flipping above when there's no room below), moves focus into it as it opens and back to
// the trigger as it closes, closes it when focus leaves it (Tab past its end), and closes it on [data-popover-close]
// inside. From JS: popover.open(id), popover.close(id), popover.toggle(id), with the trigger's id.
// Events on the panel: popover:opened and popover:closed. Delegated from `document`, so popovers added later (a
// Livewire render, fetched HTML) work without setting up.

const VIEWPORT_EDGE = 8;
const GAP = 6;
const PANEL = '[data-popover-panel]';
const FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]):not([type="hidden"]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';

let openPanel = null;

const parts = (panel) => {
    const root = panel.closest('[data-popover]');

    return { root, trigger: root.querySelector('[data-popover-trigger]') };
};
const panelOf = (id) => {
    const trigger = document.getElementById(id);

    return trigger?.matches('[data-popover-trigger]') ? document.getElementById(trigger.getAttribute('aria-controls')) : null;
};

// Whether any of the trigger can still be seen: not scrolled out of a container that clips it (a table that scrolls
// inside itself, a modal's body) or the window, and not covered there (a table's sticky header).
function inView(trigger, panel) {
    const box = trigger.getBoundingClientRect();
    let [top, right, bottom, left] = [Math.max(box.top, 0), Math.min(box.right, window.innerWidth), Math.min(box.bottom, window.innerHeight), Math.max(box.left, 0)];
    for (let parent = trigger.parentElement; parent; parent = parent.parentElement) {
        const style = getComputedStyle(parent);
        if (/auto|scroll|hidden|clip/.test(`${style.overflowX} ${style.overflowY}`)) {
            const clip = parent.getBoundingClientRect();
            [top, right, bottom, left] = [Math.max(top, clip.top), Math.min(right, clip.right), Math.min(bottom, clip.bottom), Math.max(left, clip.left)];
        }
    }
    if (bottom - top < 1 || right - left < 1) {
        return false;
    }
    const hit = document.elementsFromPoint((left + right) / 2, (top + bottom) / 2).find((element) => !panel.contains(element));

    return !hit || trigger.contains(hit);
}

function position() {
    if (!openPanel) {
        return;
    }
    const panel = openPanel;
    const { root, trigger } = parts(panel);
    // In the top layer nothing clips it: with its trigger scrolled out of view it would point at nothing. Close it.
    if (!inView(trigger, panel)) {
        panel.hidePopover();

        return;
    }
    const box = trigger.getBoundingClientRect();
    const width = panel.offsetWidth;
    const height = panel.offsetHeight;

    // start and end follow the reading direction: end is the left edge in right-to-left pages.
    const rtl = getComputedStyle(root).direction === 'rtl';
    const align = root.dataset.align;
    const left = align === 'center'
        ? box.left + box.width / 2 - width / 2
        : (align === 'end') !== rtl ? box.right - width : box.left;
    panel.style.left = `${Math.min(Math.max(left, VIEWPORT_EDGE), window.innerWidth - width - VIEWPORT_EDGE)}px`;

    // Below by default; above when it fits there and not below. Fitting neither, the roomier side wins and the panel
    // scrolls in that room.
    panel.style.maxHeight = '';
    const roomBelow = window.innerHeight - VIEWPORT_EDGE - (box.bottom + GAP);
    const roomAbove = box.top - GAP - VIEWPORT_EDGE;
    const up = height > roomBelow && (height <= roomAbove || roomAbove > roomBelow);
    const room = up ? roomAbove : roomBelow;
    if (height > room) {
        panel.style.maxHeight = `${Math.max(room, 0)}px`;
    }
    panel.style.top = `${up ? box.top - GAP - Math.min(height, room) : box.bottom + GAP}px`;
    panel.dataset.side = up ? 'top' : 'bottom';
}

// Popover toggle events don't bubble, so listen in the capture phase.
const focusTargets = new WeakMap();

// Focus goes into it as a dialog's does: to its first control, or to the panel itself when it's only text (read from
// the top). Marked with autofocus just before it opens, so the browser focuses it as part of opening: a script calling
// focus() as the toggle event runs is ignored, while the panel is still fading in. It starts transparent and is placed
// as it opens, so it never shows at the popover's default spot (the middle of the screen).
document.addEventListener('beforetoggle', (event) => {
    const panel = event.target;
    if (panel.matches?.(PANEL) && event.newState === 'open') {
        const target = panel.querySelector('[data-autofocus]') ?? panel.querySelector(FOCUSABLE) ?? panel;
        focusTargets.set(panel, target);
        if (!target.hasAttribute('autofocus')) {
            target.setAttribute('autofocus', '');
            target.dataset.popoverAutofocus = '';
        }
    }
}, true);

document.addEventListener('toggle', (event) => {
    const panel = event.target;
    if (!panel.matches?.(PANEL)) {
        return;
    }
    const { trigger } = parts(panel);
    const open = event.newState === 'open';
    trigger.setAttribute('aria-expanded', String(open));

    if (open) {
        openPanel = panel;
        position();
        // Only for this opening: the content may change before the next.
        panel.querySelectorAll('[data-popover-autofocus]').forEach((element) => {
            element.removeAttribute('autofocus');
            delete element.dataset.popoverAutofocus;
        });
        if (panel.hasAttribute('data-popover-autofocus')) {
            panel.removeAttribute('autofocus');
            delete panel.dataset.popoverAutofocus;
        }
        // The browser only autofocuses for a person's click or key. Opened by a script (popover.open, a Livewire event),
        // focus goes in here instead, frame by frame until it takes: while the panel is still fading in, focus() can be
        // ignored. It stops once focus is inside, the panel closes, or after half a second.
        let frames = 0;
        const into = () => {
            if (!panel.matches(':popover-open') || panel.contains(document.activeElement)) {
                return;
            }
            focusTargets.get(panel)?.focus({ preventScroll: true });
            if (!panel.contains(document.activeElement) && ++frames < 30) {
                requestAnimationFrame(into);
            }
        };
        into();
        window.addEventListener('scroll', position, true);
        window.addEventListener('resize', position);
        panel.dispatchEvent(new CustomEvent('popover:opened', { bubbles: true }));

        return;
    }

    if (openPanel === panel) {
        openPanel = null;
        window.removeEventListener('scroll', position, true);
        window.removeEventListener('resize', position);
    }
    // Esc, a close button or a script leaves focus nowhere or inside; put it back on the trigger. A click elsewhere, or
    // Tab out of the panel, keeps focus where it went.
    if (document.activeElement === document.body || panel.contains(document.activeElement)) {
        trigger.focus({ preventScroll: true });
    }
    panel.dispatchEvent(new CustomEvent('popover:closed', { bubbles: true }));
}, true);

// Focus leaving the panel (Tab past its last control, or Shift+Tab back to the trigger) closes it, as a click outside
// does. Without this, the panel would stay open behind whatever has focus now.
document.addEventListener('focusout', (event) => {
    const panel = event.target.closest?.(PANEL);
    if (panel?.matches(':popover-open') && event.relatedTarget && !panel.contains(event.relatedTarget)) {
        panel.hidePopover();
    }
});

document.addEventListener('click', (event) => {
    const closer = event.target.closest?.(`${PANEL} [data-popover-close]`);
    closer?.closest(PANEL).hidePopover();
});

function open(id) {
    const panel = panelOf(id);
    if (panel && !panel.matches(':popover-open')) {
        panel.showPopover();
    }
}

function close(id) {
    const panel = panelOf(id);
    if (panel?.matches(':popover-open')) {
        panel.hidePopover();
    }
}

export const popover = {
    open,
    close,
    toggle: (id) => (panelOf(id)?.matches(':popover-open') ? close(id) : open(id)),
};

// From a Livewire component ($this->dispatch('popover-close', id: 'filters')) or any script.
window.addEventListener('popover-open', (event) => open(event.detail?.id));
window.addEventListener('popover-close', (event) => close(event.detail?.id));

<?php

declare(strict_types=1);

namespace App\View\Widget;

use Illuminate\Container\Attributes\Scoped;
use LogicException;

/**
 * Keeps element ids unique within one response, so labels, aria-describedby and #fragments
 * always point at the right element. Scoped: a fresh set per request (and per Octane/queue cycle).
 */
#[Scoped]
final class ElementIds
{
    /** @var array<string, true> */
    private array $used = [];

    /**
     * Reserves an id for this response.
     *
     * A derived id (built from a field name) gets a -2, -3 … suffix when already taken. An explicit
     * id is one the caller chose and may reference from JS or CSS, so silently renaming it would
     * break that reference; a duplicate throws instead, which surfaces in development and tests.
     */
    public function claim(string $id, bool $explicit = false): string
    {
        if (! isset($this->used[$id])) {
            return $this->reserve($id);
        }

        if ($explicit) {
            throw new LogicException("Duplicate element id [{$id}] on this page. Give one of the widgets a different id or name.");
        }

        $suffix = 2;
        while (isset($this->used["{$id}-{$suffix}"])) {
            $suffix++;
        }

        return $this->reserve("{$id}-{$suffix}");
    }

    private function reserve(string $id): string
    {
        $this->used[$id] = true;

        return $id;
    }
}