entasis 0.11.0 → 0.13.0

package/dist/components/Popover/popover.state.svelte.js

@@ -1,38 +1,104 @@
 import { bind } from '../../utils/state.svelte.js';
 import { Registry } from '../../utils/registry.svelte.js';
-import { getContext, hasContext, onMount, setContext, untrack } from 'svelte';
+import { getContext, hasContext, onDestroy, onMount, setContext, untrack } from 'svelte';
+import { on } from 'svelte/events';
 import { useTheme } from '../Theme/theme.state.svelte.js';
-import { computePosition, autoUpdate, hide, offset, shift, flip } from '@floating-ui/dom';
 import { useScrollLock } from '../../utils/useScrollLock.svelte.js';
 import { useFocusScope } from '../../utils/useFocusScope.svelte.js';
+import { useTabBridge } from '../../utils/useTabBridge.svelte.js';
+import { composedContains, getDeepActiveElement, isTextField } from '../../utils/focus.js';
+import { provideLayer, useParentLayer } from '../../utils/layers.svelte.js';
 import { useSafeArea } from '../../utils/safeArea.svelte.js';
 import { useHoverAction } from '../../utils/useHoverAction.svelte.js';
+import { useOpenLifecycle } from '../../utils/openLifecycle.svelte.js';
+import { getInteractionType, isOpenChangeDetails, requestOpenChange, resolveOpenChangeDetails } from '../../utils/openChange.js';
+import { focusedElement, triggerActivation, triggerFocusTarget, writePopupAria } from '../../utils/trigger.js';
+import { useDirection } from '../../utils/useDirection.svelte.js';
+import { applyStateAttributes, openStateAttributes, placementAttributes, popupSideAttributes, transitionStatusAttributes } from '../../utils/stateAttributes.js';
 import { usePopoverMotion } from './popover.theme.js';
+import { applyDirectedOffset, claimPopupOpen, claimPopupSide, createPanelPositioner, directedMotion, releasePanelPosition } from './popover.position.js';
 // `bind(this, options)` installs the option properties on the instance; this type-only base
 // class is what declares them to TypeScript. (Merging an empty `interface` into the class
 // would be unsafe declaration merging: the interface promises members the class never defines.)
 const PopoverOptionsBase = class {
 };
-// The one place the trigger's semantic state becomes ARIA, for triggers the library cannot
-// pass props to (a snippet trigger carrying `{@attach popover.reference}`).
-/** Elements that may carry popup ARIA state. */
-const POPUP_CONTROL = 'button, a[href], input, select, textarea, summary, [role="button"], [role="link"], [role="combobox"], [role="menuitem"], [role="menuitemcheckbox"], [role="menuitemradio"], [role="tab"], [role="option"], [role="treeitem"], [role="gridcell"], [role="switch"], [role="checkbox"]';
-/** Elements the browser already focuses and activates from the keyboard. */
-const NATIVE_CONTROL = 'button, a[href], input, select, textarea, summary';
-const TRIGGER_ARIA = {
-    haspopup: 'aria-haspopup',
-    expanded: 'aria-expanded',
-    controls: 'aria-controls'
+/** The role a non-dialog popup's content element carries, by `haspopup`. */
+const POPUP_ROLE = {
+    menu: 'menu',
+    listbox: 'listbox',
+    tree: 'tree',
+    grid: 'grid'
+};
+/** How the open state was reached, from the change that opened it. */
+const openReasonOf = (details) => {
+    if (details.reason === 'trigger-hover')
+        return 'hover';
+    const fromTrigger = ['trigger-press', 'trigger-focus', 'list-navigation'];
+    if (fromTrigger.includes(details.reason)) {
+        return details.interaction === 'keyboard' ? 'keyboard' : 'press';
+    }
+    return 'programmatic';
+};
+/** How close to the viewport's width a touch-opened panel must be to lock page scroll, in px. */
+const TOUCH_LOCK_MARGIN = 20;
+/** A closed popover's safe area: it has none, so no point is inside it. */
+const CLOSED_SAFE_AREA = {
+    containsPoint: () => false,
+    updateAreas: () => { }
 };
 export class PopoverState extends PopoverOptionsBase {
-    triggerReference = $state(null);
+    /** The trigger that opened the popover, while it is open; `null` for a programmatic open. */
+    activeTrigger = $state(null);
+    /** The most recently attached `reference` / `trigger` element. */
+    #latestTrigger = $state(null);
+    /** The id of the role owner inside a non-dialog popup (the `role="menu"` element). */
+    #popupOwnerId = $state(null);
+    /**
+     * The trigger the panel anchors to: the one that opened it, else the most recently attached
+     * `reference` / `trigger` element.
+     */
+    triggerReference = $derived(this.activeTrigger ?? this.#latestTrigger);
     referenceElement = $derived(this.triggerReference || this.externalRef || null);
     dialogElement = $state(null);
+    /** The arrow inside the panel (`arrow`); `null` while there is none. */
+    arrowElement = $state(null);
+    /** The panel element focus moves into (inside `dialogElement`); `null` while it is not mounted. */
+    panelElement = $state(null);
     // Applied to the animated panel (not the portaled positioning wrapper) so the scale/fly
     // transition originates from the edge nearest the trigger.
     transformOrigin = $state('center center');
     // Trigger-matched width (fitTrigger), applied to the panel.
     triggerWidth = $state(null);
+    /**
+     * How the popover was opened: `hover`, `press` (pointer), `keyboard`, or `programmatic`
+     * (`open()` from code, the `open` prop, `defaultOpen`). `null` once closed.
+     */
+    openReason = $state(null);
+    /** The details of the last change that was applied, kept until the next one. */
+    lastOpenChange = $state.raw(null);
+    /** The open state `setOpen` last applied, to tell a change made from outside. */
+    #appliedOpen;
+    /** Whether a finger opened the popover (a programmatic open leaves the last change stale). */
+    get #openedByTouch() {
+        return this.openReason === 'press' && this.lastOpenChange?.interaction === 'touch';
+    }
+    /**
+     * Where the floating panel was last placed: the side it sits on (logical when a logical side
+     * was requested, `none` when `positionPanel` placed it), its alignment, and whether its anchor
+     * is scrolled out of view. `null` until the first placement lands and once the panel unmounts.
+     */
+    placement = $state(null);
+    /**
+     * The panel's styling hooks: `data-open` / `data-closed`, `data-entering` / `data-exiting`,
+     * `data-side`, `data-align` and `data-anchor-hidden` (see `popoverDataAttributes`).
+     */
+    panelAttributes = $derived({
+        ...openStateAttributes(this.isOpen),
+        ...transitionStatusAttributes(this.status),
+        ...placementAttributes(this.placement
+            ? { side: this.placement.side, align: this.placement.align ?? undefined }
+            : undefined, { anchorHidden: this.placement?.anchorHidden })
+    });
     parent = getContext('popover');
     // Nested popovers join while they mount and leave when torn down; see `Registry`.
     #children = new Registry();
@@ -40,24 +106,65 @@ export class PopoverState extends PopoverOptionsBase {
         return this.#children.items;
     }
     hasChildOpen = $derived(this.children.some((d) => d.isOpen));
-    hasTransitioned = $state(false);
     theme = useTheme();
-    // The mobile sheet delegates to a Dialog, which registers its own layer.
-    // An inline panel sits in the flow and is not dismissed by an outside press; Escape still
-    // reaches it while it is the top layer.
-    layer = this.theme.layers.register({
-        kind: 'popover',
-        isOpen: () => this.isOpen && !this.isMobileSheet,
-        isModal: () => false,
-        dismissOnEscape: () => this.closeOnEscape,
-        dismissOnOutside: () => !this.inline && this.closeOnClickOutside && this.hasTransitioned,
-        onDismiss: () => this.close(),
-        state: this
-    });
+    /**
+     * Open → entering → open → exiting → closed; completes even when no transition plays.
+     * Created in the constructor: it reads the options as it starts, after `bind` installs them.
+     */
+    lifecycle;
+    /** Where the panel is in its open/close lifecycle; see `PopoverApi.status`. */
+    get status() {
+        return this.lifecycle.status;
+    }
+    /** @deprecated Read `status === 'open'`; kept for one minor. */
+    get hasTransitioned() {
+        return this.lifecycle.status === 'open';
+    }
+    /**
+     * What only an open popover needs, while it is open or closing; see `openSession`. A closed
+     * popover (every Select, date input and row menu on a page) builds none of it.
+     */
+    #session = $state.raw(null);
+    /** `#session` as last written, for teardowns, which must not read `$state`. */
+    #currentSession = null;
+    /** The layer this popover renders inside (a Dialog, a parent menu), read when it opens. */
+    #parentLayer = useParentLayer();
+    /** The popover's layer while it is open or closing, else `null`. */
+    get layer() {
+        return this.#session?.layer ?? null;
+    }
+    /**
+     * Whether no open layer sits above this popover, except a tooltip: a tooltip never takes focus
+     * or holds a control, so one showing over a button in the panel (or over the trigger) must not
+     * count as something that took over from it. `false` while closed.
+     */
+    get isTopLayer() {
+        return this.#session?.isTopLayer ?? false;
+    }
+    /**
+     * The safe area around the trigger and the panel (menus ask it whether the pointer is on its way
+     * to an open submenu). A closed popover has none: no point is inside it.
+     */
+    get safeArea() {
+        return this.#session?.safeArea ?? CLOSED_SAFE_AREA;
+    }
     computedSize = $derived(this.theme.resolveResponsiveProps(this.size, 'normal'));
     // `inline` wins over `mobileSheet`: an in-flow panel never becomes a sheet.
     isMobileSheet = $derived(!this.inline && !!this.mobileSheet && this.theme.isMobile);
     computedMode = $derived(this.inline ? 'inline' : this.isMobileSheet ? 'mobileSheet' : 'floating');
+    /**
+     * Whether the panel is modal right now: a floating panel with `modal` contains Tab and makes the
+     * page behind it `inert`. An inline panel sits in the page and never is; the mobile sheet is a
+     * modal Dialog of its own.
+     */
+    isModal = $derived(!!this.modal && this.computedMode === 'floating');
+    /**
+     * Whether the panel holds dialog content. Menus, listboxes, trees and grids render a plain
+     * wrapper instead of an unnamed `<dialog>`, and their trigger controls the role owner inside.
+     */
+    isDialogPopup = $derived((this.haspopup ?? 'dialog') === 'dialog');
+    /** The id of the element `aria-controls` points at while open. */
+    controlsId = $derived(this.isDialogPopup ? this.id : (this.#popupOwnerId ?? this.id));
     /**
      * Trigger state in the library's semantic vocabulary: spread on the built-in Button, and
      * written as the matching ARIA attributes by `reference` for a snippet trigger.
@@ -65,257 +172,990 @@ export class PopoverState extends PopoverOptionsBase {
     triggerProps = $derived({
         haspopup: this.haspopup ?? 'dialog',
         expanded: this.isOpen,
-        controls: this.isOpen && !this.isMobileSheet ? this.id : undefined
-    });
-    // Non-modal: no Tab containment or `inert`; optional initial focus, always restores.
-    focusScope = useFocusScope({
-        isActive: () => this.isOpen && !this.isMobileSheet && this.layer.isTop,
-        trap: () => false,
-        initialFocus: () => this.focusOnOpen ?? false,
-        returnTo: () => this.triggerReference
+        controls: this.isOpen && !this.isMobileSheet ? this.controlsId : undefined
     });
+    /**
+     * Whether Tab is bridged between the trigger and the portaled panel: a floating dialog popup
+     * opened from a trigger, unless `tabBridge` is off. Menus, listboxes and the like manage focus
+     * themselves, a modal panel contains Tab on its own, and a panel the pointer merely hovered
+     * open is not a Tab destination.
+     */
+    get tabBridgeActive() {
+        return (this.isOpen &&
+            this.tabBridge &&
+            !this.isModal &&
+            this.computedMode === 'floating' &&
+            this.isDialogPopup &&
+            this.openReason !== 'hover' &&
+            this.isTopLayer &&
+            this.placement !== null &&
+            this.panelElement !== null &&
+            this.#bridgeAnchor() !== null);
+    }
+    /**
+     * Whether focus moving away closes the popover: a floating dialog popup that is not modal (a
+     * modal one keeps focus), not opened by the pointer hovering, and `closeOnFocusOut` (by
+     * default, `closeOnClickOutside`). Menus and lists steer focus themselves.
+     */
+    get closesOnFocusOut() {
+        return ((this.closeOnFocusOut ?? this.closeOnClickOutside) &&
+            !this.isModal &&
+            this.computedMode === 'floating' &&
+            this.isDialogPopup &&
+            this.openReason !== 'hover');
+    }
     // Mode preset from `popoverTheme.motion`, through the override ladder
     // (registry → `setPopoverTheme` → instance `theme.motion` → `transition` prop).
     resolveMotion = usePopoverMotion();
     computedTransition = $derived(this.resolveMotion({ mode: this.computedMode }, { motion: this.motion, transition: this.transition }));
     computedPosition = $derived(this.theme.resolveResponsiveProps(this.position, 'top'));
-    // Hook instances
-    safeArea = useSafeArea({
-        isActive: () => this.isOpen && this.closeOnMouseLeave && this.children.filter((d) => d.isOpen).length === 0,
-        callback: () => this.close(),
-        offset: 15,
-        debug: () => this.debugSafeArea
-    });
     hoverAction = useHoverAction({
-        isActive: () => this.openOnHover && !this.isOpen,
-        onMouseEnter: () => {
-            this.open();
+        isActive: () => this.openOnHover && !this.modal && !this.isOpen,
+        onMouseEnter: (event) => {
+            this.setOpen(true, {
+                reason: 'trigger-hover',
+                event,
+                trigger: this.#hoveredTrigger ?? undefined,
+                interaction: 'mouse'
+            });
         },
-        delay: this.delay
+        // A function, read on each enter: field initialisers run before `bind(this, options)`
+        // installs the options, so a plain `this.delay` here would be `undefined` (no delay).
+        delay: () => this.delay,
+        // Root hover popovers share the warm-up with tooltips and hover cards. Submenus keep their
+        // delay: it is what lets the pointer cross sibling rows on the way to an open submenu.
+        group: () => (this.openOnHover && !this.parent ? this.theme.hoverIntent : null),
+        isOpen: () => this.isOpen,
+        contains: (node) => !!this.dialogElement?.contains(node)
     });
     addChild = (child) => () => this.#children.add(child);
+    /** The element the panel is anchored to, for its writing direction. */
+    #anchorElement = () => {
+        const reference = this.referenceElement;
+        if (reference instanceof HTMLElement)
+            return reference;
+        const context = reference?.contextElement;
+        return context instanceof HTMLElement ? context : null;
+    };
+    /** The reading direction logical sides and start/end alignment resolve with. */
+    #direction = useDirection(this.#anchorElement);
     constructor(options) {
         super();
         bind(this, options);
+        this.lifecycle = useOpenLifecycle({
+            isOpen: () => this.isOpen,
+            external: () => this.isMobileSheet,
+            onAfterOpen: () => this.onAfterOpen?.(this),
+            onAfterClose: () => {
+                this.#currentSession?.focusScope.restore();
+                this.onAfterClose?.(this);
+                this.openReason = null;
+                this.#setActiveTrigger(null);
+                this.#opener = null;
+            }
+        });
         setContext('popover', this);
+        // Layers registered inside the panel (a nested popover, a dialog it opens) sit above this
+        // popover's layer, which exists only while it is open.
+        provideLayer(() => this.#currentSession?.layer ?? null);
+        // The parent registers its children whatever their payload type.
         if (this.parent)
             onMount(this.parent.addChild(this));
-        useScrollLock({
-            isActive: () => this.lockScroll && !this.inline && !this.isMobileSheet && !this.parent && this.isOpen
+        // Details describe the change `setOpen` made: an open state moved from outside (the bound
+        // `open` prop) leaves none, so a later close does not read the one that opened it.
+        $effect.pre(() => {
+            const open = this.isOpen;
+            untrack(() => {
+                if (this.#appliedOpen !== open)
+                    this.lastOpenChange = null;
+                this.#appliedOpen = open;
+            });
+        });
+        onDestroy(() => {
+            this.#destroyed = true;
         });
+        // An open state that did not come through `setOpen` (the `open` prop, `defaultOpen`) is a
+        // programmatic open: focus returns to whatever had it when it opened.
+        $effect.pre(() => {
+            const open = this.isOpen;
+            untrack(() => {
+                const committed = this.#committed;
+                this.#committed = null;
+                if (committed === open || !open)
+                    return;
+                this.openReason = 'programmatic';
+                this.#opener = focusedElement();
+            });
+        });
+    }
+    /**
+     * Whether the open-only machinery is needed: while the popover is open, and until its closing
+     * transition has finished. `PopoverSession` is rendered while this holds.
+     */
+    get sessionActive() {
+        return this.isOpen || this.lifecycle.status !== 'closed';
     }
-    toggle = () => {
-        this.setOpen(!this.isOpen);
+    /**
+     * Builds what only an open popover needs: its layer, focus scope, safe area, Tab bridge, scroll
+     * lock and focus-out watch, and registers the attached triggers with them. `PopoverSession`
+     * calls it during its initialisation while `sessionActive` holds; everything it creates goes
+     * with that component.
+     */
+    openSession = () => {
+        // The mobile sheet delegates to a Dialog, which registers its own layer.
+        // An inline panel sits in the flow and is not dismissed by an outside press; Escape still
+        // reaches it while it is the top layer.
+        const layer = this.theme.layers.register({
+            kind: 'popover',
+            isOpen: () => this.isOpen && !this.isMobileSheet,
+            isModal: () => this.isModal,
+            dismissOnEscape: () => this.closeOnEscape,
+            dismissOnOutside: () => !this.inline && this.closeOnClickOutside,
+            onDismiss: (request) => this.setOpen(false, request),
+            state: this,
+            // Read here, not from the session component's context, which is this popover's own.
+            parent: untrack(this.#parentLayer)
+        });
+        const isTopLayer = $derived.by(() => {
+            const open = this.theme.layers.open;
+            const index = open.indexOf(layer);
+            if (index < 0)
+                return false;
+            return open.slice(index + 1).every(({ state }) => {
+                // The shared tooltip surface is known by id, so it counts before its panel has
+                // mounted: the scope would otherwise release and re-apply `inert` around the tooltip.
+                return (state instanceof PopoverState &&
+                    (`${state.id}-tooltip` === this.theme.tooltipId ||
+                        !!state.panelElement?.querySelector('[role="tooltip"]')));
+            });
+        });
+        // Non-modal: no Tab containment or `inert`; optional initial focus. Focus goes back when it
+        // was inside the panel, or when a trigger opened the popover (Safari does not focus a button
+        // on click, so a press and Escape leave focus on <body>). A popover with neither, such as a
+        // combobox list, leaves focus alone, even when the control that kept it blurred on purpose.
+        // A floating panel is hidden until its first placement lands, and nothing in it can take
+        // focus before then, so initial focus waits for that placement.
+        const focusScope = useFocusScope({
+            isActive: () => this.isOpen &&
+                !this.isMobileSheet &&
+                isTopLayer &&
+                (this.computedMode !== 'floating' || this.placement !== null),
+            trap: () => this.isModal,
+            inertSiblings: () => this.isModal,
+            initialFocus: () => this.focusOnOpen ?? (this.isModal ? 'first' : false),
+            restoreFocus: () => this.#focusEntered || this.activeTrigger !== null,
+            returnTo: () => this.#returnTarget(),
+            // Focus that moved on by itself (Tab past the end of the panel) is not taken back.
+            focusOnClose: () => (this.lastOpenChange?.reason === 'focus-out' ? false : this.focusOnClose),
+            closeDetails: () => this.lastOpenChange
+        });
+        // The safe area tracks every open popover (menus ask it whether the pointer is on its way to
+        // an open submenu), but leaving it closes only a popover the pointer opened by hovering: one
+        // opened by a press, the keyboard or code stays until it is dismissed.
+        const safeArea = useSafeArea({
+            isActive: () => this.isOpen && this.closeOnMouseLeave && this.children.every((child) => !child.isOpen),
+            callback: (event) => {
+                if (this.openReason !== 'hover')
+                    return;
+                this.setOpen(false, { reason: 'trigger-hover', event, interaction: 'mouse' });
+            },
+            offset: 15,
+            debug: () => this.debugSafeArea,
+            closeDelay: () => this.closeDelay
+        });
+        // Every attached trigger counts as inside the layer and anchors the safe area.
+        // eslint-disable-next-line svelte/prefer-svelte-reactivity -- teardown bookkeeping, never rendered
+        const triggers = new Map();
+        const session = {
+            layer,
+            focusScope,
+            safeArea,
+            get isTopLayer() {
+                return isTopLayer;
+            },
+            addTrigger: (node) => {
+                if (triggers.has(node))
+                    return;
+                triggers.set(node, [layer.node(node), safeArea.anchorReference(node)]);
+            },
+            removeTrigger: (node) => {
+                triggers.get(node)?.forEach((off) => off?.());
+                triggers.delete(node);
+            }
+        };
+        untrack(() => {
+            for (const node of this.#triggers.keys())
+                session.addTrigger(node);
+            this.#currentSession = session;
+            this.#session = session;
+        });
+        onDestroy(() => {
+            for (const node of [...triggers.keys()])
+                session.removeTrigger(node);
+            if (this.#currentSession !== session)
+                return;
+            this.#currentSession = null;
+            this.#session = null;
+        });
+        useTabBridge({
+            isActive: () => this.tabBridgeActive,
+            anchor: this.#bridgeAnchor,
+            panel: () => this.panelElement,
+            // A trigger inside another popover's panel tabs on within that panel.
+            boundary: () => {
+                const anchor = this.#bridgeAnchor();
+                const parentPanel = this.parent?.panelElement;
+                return anchor && parentPanel && parentPanel.contains(anchor) ? parentPanel : undefined;
+            },
+            // The bridge has already moved focus on; whether that closes the panel is the same
+            // `closeOnFocusOut` decision the focus listener below makes.
+            onLeave: (event) => {
+                if (!this.closesOnFocusOut)
+                    return;
+                void this.setOpen(false, { reason: 'focus-out', event, interaction: 'keyboard' });
+            }
+        });
+        // Focus that was inside the popover (or on its trigger) moving on closes it. A popover whose
+        // panel focus never entered is left to outside presses: Tab, a click or a screen reader's
+        // virtual cursor elsewhere on the page only counts once focus has been in the tree. Judged
+        // in a microtask, where focus has settled and reactive state is safe to read: `focus()`
+        // calls made by a closing popup's teardown dispatch this event in the middle of a flush.
+        $effect(() => {
+            if (!this.isOpen || !this.closesOnFocusOut)
+                return;
+            const doc = this.dialogElement?.ownerDocument;
+            if (!doc)
+                return;
+            let within = untrack(() => this.#focusInTree(getDeepActiveElement(doc)));
+            let scheduled = false;
+            return on(doc, 'focusin', (event) => {
+                if (scheduled)
+                    return;
+                scheduled = true;
+                queueMicrotask(() => {
+                    scheduled = false;
+                    if (!this.isOpen || this.#appliedOpen === false || !this.closesOnFocusOut)
+                        return;
+                    const active = getDeepActiveElement(doc);
+                    if (!active || active === doc.body)
+                        return;
+                    if (this.#focusInTree(active)) {
+                        within = true;
+                        return;
+                    }
+                    if (!within)
+                        return;
+                    within = false;
+                    this.setOpen(false, { reason: 'focus-out', event, interaction: 'keyboard' });
+                });
+            });
+        });
+        // A touch-opened popover is non-modal and a finger scrolls the page under it, so it locks
+        // scroll only when its panel spans the viewport, where there is nothing left to scroll to.
+        let panelSpansViewport = $state(false);
+        $effect(() => {
+            const panel = this.dialogElement;
+            if (!panel || !this.#openedByTouch) {
+                panelSpansViewport = false;
+                return;
+            }
+            const measure = () => {
+                const view = panel.ownerDocument.defaultView;
+                panelSpansViewport =
+                    !!view && panel.getBoundingClientRect().width >= view.innerWidth - TOUCH_LOCK_MARGIN;
+            };
+            measure();
+            const observer = new ResizeObserver(measure);
+            observer.observe(panel);
+            return () => observer.disconnect();
+        });
+        // A hover-opened popover is a preview the pointer can leave: the page keeps scrolling.
+        useScrollLock({
+            isActive: () => this.lockScroll &&
+                !this.inline &&
+                !this.isMobileSheet &&
+                !this.parent &&
+                this.isOpen &&
+                this.openReason !== 'hover' &&
+                (!this.#openedByTouch || panelSpansViewport)
+        });
+        // The point the pointer was at belongs to one opening: a later keyboard open must not reuse it.
+        $effect(() => {
+            if (!this.isOpen)
+                return;
+            return () => {
+                this.#anchorOffset = null;
+            };
+        });
+        // The trigger (or `ref` element) reports the side its placed panel sits on, so a theme can
+        // flatten the corner the panel attaches to.
+        $effect(() => {
+            const anchor = this.referenceElement;
+            if (!(anchor instanceof HTMLElement))
+                return;
+            const { 'data-popup-side': side } = popupSideAttributes(this.placement?.side);
+            claimPopupSide(anchor, this, side ?? null);
+            return () => claimPopupSide(anchor, this, null);
+        });
+        // The element the panel is anchored to (the trigger that opened it, or the `ref` element)
+        // carries `data-popup-open` while it is open. Claimed like the side: a menu and its tooltip
+        // share a trigger, and the tooltip closing leaves the menu's hook in place.
+        $effect(() => {
+            const anchor = this.referenceElement;
+            if (!(anchor instanceof HTMLElement))
+                return;
+            claimPopupOpen(anchor, this, this.isOpen);
+            return () => claimPopupOpen(anchor, this, false);
+        });
+        // The panel's open state and transition phase, written from here rather than only by the
+        // template: Svelte pauses the effects of a block while its out-transition plays, so the
+        // panel's own attributes would stay `data-open` until it is gone. The session lives until
+        // the exit ends, so `data-closed` and `data-exiting` reach the closing panel.
+        $effect(() => {
+            const panel = this.panelElement;
+            if (!panel)
+                return;
+            applyStateAttributes(panel, {
+                ...openStateAttributes(this.isOpen),
+                ...transitionStatusAttributes(this.lifecycle.status)
+            });
+        });
     };
-    open = () => {
-        this.setOpen(true);
+    /** Toggles the popover. A press on the trigger of a popover the pointer opened by hovering pins it open instead. */
+    toggle = (input) => {
+        const details = this.#details(input);
+        if (this.isOpen && details.reason === 'trigger-press') {
+            const anchor = this.triggerReference;
+            if (this.openReason === 'hover') {
+                // Hovered open, then pressed: the press keeps it open and makes it stay.
+                this.#openRequests += 1;
+                this.openReason = openReasonOf(details);
+                return;
+            }
+            if (details.trigger &&
+                anchor &&
+                details.trigger !== anchor &&
+                this.#triggers.has(details.trigger)) {
+                // Another trigger of the same popover: the panel moves to it and stays open.
+                this.#openRequests += 1;
+                this.#setActiveTrigger(details.trigger);
+                this.#opener = triggerFocusTarget(details.trigger, details.event);
+                return;
+            }
+        }
+        this.setOpen(!this.isOpen, details);
     };
-    close = () => {
-        this.setOpen(false);
+    open = (input) => {
+        this.setOpen(true, input);
     };
+    /** Closes the popover. Returns `false` when `onOpenChange` cancelled the change. */
+    close = (input) => this.setOpen(false, input);
     /** Calls to `setOpen`, direct or through `open`, `close` and `toggle`, unchanged state included. */
     #openRequests = 0;
-    setOpen = (nextOpen) => {
-        this.#openRequests += 1;
-        if (this.isOpen === nextOpen)
+    #destroyed = false;
+    /** The open state `setOpen` last wrote, until the effect that sees it has run. */
+    #committed = null;
+    /** Where focus returns when the popover closes; see `#returnTarget`. */
+    #opener = null;
+    /** Whether focus has been inside the mounted panel. */
+    #focusEntered = false;
+    // Triggers: every element attached through `reference` (or `trigger`), with the order they
+    // attached in. Plain fields, not `$state`: detach teardowns compare against them, and a
+    // `$state` read in teardown can return the value from before the change that triggered it.
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity -- teardown bookkeeping, never rendered
+    #triggers = new Map();
+    #triggerSequence = 0;
+    /** Triggers attached during the current flush: a re-rendered trigger's replacement. */
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity -- teardown bookkeeping, never rendered
+    #recentTriggers = new Set();
+    #latestTriggerNode = null;
+    #activeTriggerNode = null;
+    #hoveredTrigger = null;
+    /** The press dispatching right now on a trigger, so `toggle()` from its handler knows it. */
+    #press = null;
+    /** The pointer type of the last press on a trigger, for clicks that do not carry one. */
+    #pointerType = null;
+    #setActiveTrigger(node) {
+        this.#activeTriggerNode = node;
+        this.activeTrigger = node;
+    }
+    #setLatestTrigger(node) {
+        this.#latestTriggerNode = node;
+        this.#latestTrigger = node;
+    }
+    /** Whether the panel still has an anchor in the document: a trigger, else the `ref` prop. */
+    #hasAnchor = () => {
+        const anchor = this.#activeTriggerNode ?? this.#latestTriggerNode ?? this.externalRef;
+        if (!anchor)
+            return false;
+        // A floating-ui virtual element (a cursor point) has no DOM presence to lose.
+        return !(anchor instanceof Element) || anchor.isConnected;
+    };
+    /**
+     * Closes an open popover whose anchor left the document, so `onOpenChange` reports it with
+     * `reason: 'trigger-unmount'`. Skipped while the component itself is being destroyed.
+     */
+    #closeIfAnchorLost = () => {
+        if (this.#destroyed || !this.isOpen || this.#hasAnchor())
             return;
-        this.isOpen = nextOpen;
-        this.onOpenChange?.(nextOpen);
+        this.setOpen(false, { reason: 'trigger-unmount' });
     };
-    applyDirectedTransition = (node, placement) => {
-        const side = placement.split('-')[0];
-        const alignment = placement.split('-')[1];
-        const axis = side === 'top' || side === 'bottom' ? 'y' : 'x';
-        const value = side === 'top' || side === 'left' ? 10 : -10;
-        const transformOriginY = side === 'top' ? 'bottom' : side === 'bottom' ? 'top' : 'center';
-        const transformOriginX = alignment === 'start' ? 'left' : alignment === 'end' ? 'right' : 'center';
-        this.transformOrigin = `${transformOriginX} ${transformOriginY}`;
-        Object.assign(this.computedTransition.in, {
-            [axis]: value
-        });
-        Object.assign(this.computedTransition.out, {
-            [axis]: value
+    /**
+     * Focus goes back to the trigger that opened the popover (or the control pressed inside it),
+     * and after a programmatic open to the element that had focus when it opened. `null` lets the
+     * focus scope use the element focused when the panel mounted.
+     */
+    #returnTarget = () => {
+        if (this.#opener?.isConnected)
+            return this.#opener;
+        if (this.openReason === 'programmatic' || this.openReason === null)
+            return null;
+        const trigger = this.activeTrigger ?? this.triggerReference;
+        return trigger ? triggerFocusTarget(trigger) : null;
+    };
+    /**
+     * The control Tab starts from and returns to: the one that opened the popover, else the focusable
+     * part of the trigger. `null` without a registered trigger (a popover anchored to a `ref`), and
+     * for a text field (a date or color input): Tab there moves on to the next field of a form.
+     */
+    #bridgeAnchor = () => {
+        const trigger = this.triggerReference;
+        if (!trigger || !this.#triggers.has(trigger))
+            return null;
+        const anchor = this.openReason !== 'programmatic' && this.#opener?.isConnected
+            ? this.#opener
+            : triggerFocusTarget(trigger);
+        return anchor && !isTextField(anchor) ? anchor : null;
+    };
+    /**
+     * Whether `target` belongs to this popover: its panel, a trigger, the `ref` element, or a popup
+     * opened from any of them (a nested popover, a dialog the panel opened).
+     */
+    #focusInTree = (target) => {
+        if (!target)
+            return false;
+        const external = this.externalRef;
+        if (external instanceof Node && composedContains(external, target))
+            return true;
+        // Without a layer (closed) nothing opened from the popover is showing.
+        const own = this.layer;
+        if (!own)
+            return false;
+        const open = this.theme.layers.open;
+        // A modal layer opened above this popover (a Dialog or confirmation the panel's content
+        // opened, rendered elsewhere) holds focus while the popover waits underneath it.
+        const above = open.indexOf(own);
+        if (above >= 0 &&
+            open
+                .slice(above + 1)
+                .some((layer) => layer.isModal && [...layer.nodes].some((node) => composedContains(node, target))))
+            return true;
+        return open.some((layer) => {
+            for (let current = layer; current; current = current.parent) {
+                if (current !== own)
+                    continue;
+                return [...layer.nodes].some((node) => composedContains(node, target));
+            }
+            return false;
         });
     };
-    place = async (node, mount = false) => {
-        // Inline panels are laid out by the document, never by floating-ui.
-        if (this.inline || this.isMobileSheet || !this.referenceElement) {
-            this.triggerWidth = null;
-            return;
-        }
-        if (!mount && !this.hasTransitioned) {
-            return;
+    /** The details for a request, filled in from the trigger press it happens during. */
+    #details = (input) => {
+        if (isOpenChangeDetails(input))
+            return input;
+        const event = input instanceof Event ? input : input?.event;
+        const press = this.#press && (!event || event === this.#press.event) ? this.#press : null;
+        const fallback = press
+            ? {
+                reason: press.reason,
+                event: press.event,
+                trigger: press.node,
+                interaction: getInteractionType(press.event, this.#pointerType)
+            }
+            : { interaction: getInteractionType(event, this.#pointerType) };
+        return resolveOpenChangeDetails(input, fallback);
+    };
+    /**
+     * Requests an open-state change. `onOpenChange(nextOpen, details)` runs first; when it calls
+     * `details.cancel()` nothing changes. Returns `false` when the change was cancelled.
+     */
+    setOpen = (nextOpen, input) => {
+        this.#openRequests += 1;
+        if (this.isOpen === nextOpen) {
+            // A press on the trigger of a popover the pointer opened by hovering pins it open, the
+            // same as `toggle()` does: a menu's submenu trigger opens its submenu with `open()`.
+            if (nextOpen && this.openReason === 'hover') {
+                const pressed = this.#details(input);
+                if (pressed.reason === 'trigger-press')
+                    this.openReason = openReasonOf(pressed);
+            }
+            return true;
         }
-        if (this.fitTrigger) {
-            this.triggerWidth = this.referenceElement.getBoundingClientRect().width;
+        const details = this.#details(input);
+        if (!requestOpenChange(this.onOpenChange, nextOpen, details))
+            return false;
+        // A hover open still waiting on its delay belongs to the state before this change: left
+        // pending, it would reopen a popover the user just closed by click or Escape.
+        this.hoverAction.cancel();
+        if (nextOpen) {
+            const trigger = details.trigger && this.#triggers.has(details.trigger) ? details.trigger : null;
+            this.#setActiveTrigger(trigger);
+            this.openReason = openReasonOf(details);
+            this.#opener =
+                this.openReason === 'programmatic'
+                    ? focusedElement()
+                    : trigger
+                        ? triggerFocusTarget(trigger, details.event)
+                        : null;
         }
-        const custom = this.positionPanel?.({ panel: node, reference: this.referenceElement });
-        if (custom) {
-            if (custom.minWidth != null)
-                this.triggerWidth = custom.minWidth;
-            Object.assign(node.style, {
-                position: 'fixed',
-                left: `${custom.x}px`,
-                top: `${custom.y}px`,
-                visibility: ''
-            });
-            this.safeArea.updateAreas();
+        this.lastOpenChange = details;
+        this.#appliedOpen = nextOpen;
+        this.#committed = nextOpen;
+        this.isOpen = nextOpen;
+        return true;
+    };
+    /**
+     * Points the panel's motion at the side facing the reference, for the resolved placement: the
+     * scale origin and the exit follow every placement (a flip included), the entrance only the
+     * placement made before it plays.
+     */
+    applyDirectedTransition = (placement, { direction = 'ltr', intro = true } = {}) => {
+        const motion = directedMotion(placement, direction);
+        this.transformOrigin = motion.transformOrigin;
+        if (intro)
+            applyDirectedOffset(this.computedTransition.in, motion);
+        applyDirectedOffset(this.computedTransition.out, motion);
+    };
+    /** Records a placement, reassigning only what changed so styling hooks don't churn on scroll. */
+    #setPlacement = ({ side, align, anchorHidden }) => {
+        const current = this.placement;
+        if (current?.side === side && current.align === align && current.anchorHidden === anchorHidden)
             return;
-        }
-        const { x, y, strategy, placement } = await computePosition(this.referenceElement, node, {
-            strategy: 'fixed',
-            placement: this.computedPosition,
-            middleware: [
-                offset(this.offset ?? 4),
-                flip({
-                    mainAxis: true,
-                    crossAxis: true,
-                    padding: 20
-                }),
-                shift({
-                    mainAxis: true,
-                    crossAxis: true,
-                    padding: 20
-                }),
-                hide()
-            ]
-        });
-        Object.assign(node.style, {
-            position: strategy,
-            left: `${x}px`,
-            top: `${y}px`,
-            // computePosition is async: unhide only once the first placement lands, so the
-            // panel never flashes at top-left (0,0) before floating-ui resolves.
-            visibility: ''
-        });
-        this.safeArea.updateAreas();
-        if (mount && !this.hasTransitioned && this.directedTransition) {
-            this.applyDirectedTransition(node, placement);
-        }
+        this.placement = { side, align, anchorHidden };
     };
+    /**
+     * Where the pointer last was over the trigger while the popover was closed, in viewport
+     * coordinates. Frozen while open: `anchorTo: 'line'` anchors to the line under it.
+     */
+    #anchorOffset = null;
+    /**
+     * The captured point resolved against where its reference is now: held as an offset from the
+     * reference's box, it stays on the same line when the page or a scroll ancestor scrolls.
+     */
+    #anchorPoint = () => {
+        const offset = this.#anchorOffset;
+        if (!offset)
+            return null;
+        const rect = offset.reference.getBoundingClientRect();
+        return { x: rect.left + offset.dx, y: rect.top + offset.dy };
+    };
+    // floating-ui placement lives in `popover.position.ts`. Its inputs are read when a placement
+    // runs: the mount placement runs inside the `dialog` attachment, so a change to any of them
+    // re-places an open panel.
+    #positioner = createPanelPositioner({
+        reference: () => this.referenceElement,
+        // Inline panels and mobile sheets are laid out by the document, never by floating-ui.
+        floating: () => !this.inline && !this.isMobileSheet,
+        // Untracked: floating-ui runs its first observed update synchronously inside the panel
+        // attachment, which would otherwise re-run (and re-mount the placement) when the opening
+        // transition ends. The catch-up placement in `dialog` covers that moment instead.
+        settled: () => untrack(() => this.lifecycle.status === 'open'),
+        placement: () => this.computedPosition,
+        offset: () => this.offset,
+        fitTrigger: () => this.fitTrigger,
+        positionPanel: () => this.positionPanel,
+        direction: this.#direction,
+        collisionBoundary: () => this.collisionBoundary,
+        fallbackAxisSide: () => this.fallbackAxisSide,
+        anchorTo: () => this.anchorTo,
+        anchorPoint: this.#anchorPoint,
+        arrow: () => (this.arrow && this.computedMode === 'floating' ? this.arrowElement : null),
+        setMinWidth: (width) => {
+            this.triggerWidth = width;
+        },
+        // `positionPanel` places synchronously, inside the panel attachment: nothing read here may
+        // become one of its dependencies.
+        onPlace: ({ placement, side, align, anchorHidden, direction, mount }) => untrack(() => {
+            this.#setPlacement({ side, align, anchorHidden });
+            this.safeArea.updateAreas();
+            if (placement && this.directedTransition) {
+                this.applyDirectedTransition(placement, {
+                    direction,
+                    intro: mount && this.lifecycle.status !== 'open'
+                });
+            }
+        })
+    });
+    /** Places the floating panel against its reference once; see `PanelPositioner.place`. */
+    place = (node, mount = false) => this.#positioner.place(node, mount);
+    /** Attachment for the positioning wrapper (`<dialog>`, or a `<div>` for a non-dialog popup). */
     dialog = (node) => {
         this.dialogElement = node;
         if (this.inline) {
             // No portal, no fixed placement: the wrapper stays where the component is rendered.
             this.triggerWidth = null;
-            Object.assign(node.style, {
-                position: '',
-                left: '',
-                top: '',
-                visibility: ''
-            });
+            releasePanelPosition(node, true);
             return () => {
                 this.dialogElement = null;
             };
         }
         if (this.isMobileSheet) {
             this.triggerWidth = null;
-            Object.assign(node.style, {
-                position: '',
-                left: '',
-                top: ''
-            });
+            releasePanelPosition(node, false);
             return () => {
                 this.dialogElement = null;
             };
         }
-        // Hide until place() resolves (async computePosition), preventing the top-left flash.
-        node.style.visibility = 'hidden';
-        void this.place(node, true);
-        const cleanup = autoUpdate(this.referenceElement, node, () => this.place(node));
+        const reference = this.referenceElement;
+        // The anchor can go while the panel's outro still runs (its trigger unmounted): the panel
+        // keeps its last place, since floating-ui cannot observe a missing reference.
+        if (!reference) {
+            return () => {
+                this.dialogElement = null;
+                queueMicrotask(this.#closeIfAnchorLost);
+            };
+        }
+        // A reference that leaves the document closes the popover instead of being placed.
+        const cleanup = this.#positioner.track(node, reference, this.#closeIfAnchorLost);
+        // Changes observed during the opening transition are not placed; catch up once it ends,
+        // so content that resized while opening doesn't leave the panel misplaced.
+        $effect(() => {
+            if (this.lifecycle.status === 'open')
+                untrack(() => void this.place(node));
+        });
         return () => {
             cleanup();
             this.dialogElement = null;
+            // Forget the placement once the panel is gone, not when it is only placed again (a new
+            // `position`), so the styling hooks and the focus gate don't flicker in between.
+            queueMicrotask(() => {
+                if (!this.dialogElement)
+                    this.placement = null;
+            });
+            // The panel also leaves when its `ref` anchor does (`bind:this` resets it to null),
+            // and without an outro that happens before the positioner's observers can report the
+            // detached node: judge the anchor once the flush settles, so the popover closes
+            // instead of staying open and reappearing when the anchor returns. A no-op when the
+            // popover closed or was destroyed, or when another anchor took over.
+            queueMicrotask(this.#closeIfAnchorLost);
         };
     };
     panel = (node) => {
         return untrack(() => {
             const cleanups = [];
-            cleanups.push(this.layer.node(node));
-            cleanups.push(this.focusScope.attachment(node));
-            cleanups.push(this.safeArea.floatingReference?.(node));
+            this.panelElement = node;
+            cleanups.push(() => {
+                if (this.panelElement === node)
+                    this.panelElement = null;
+            });
+            this.#focusEntered = node.contains(node.ownerDocument.activeElement);
+            cleanups.push(on(node, 'focusin', () => {
+                this.#focusEntered = true;
+            }));
+            // The session exists whenever the panel does: it is rendered first, while open or closing.
+            const session = this.#currentSession;
+            if (session) {
+                cleanups.push(session.layer.node(node));
+                cleanups.push(session.focusScope.attachment(node));
+                cleanups.push(session.safeArea.floatingReference(node));
+            }
+            if (!this.isDialogPopup)
+                cleanups.push(this.#labelPopupOwner(node));
             return () => {
                 cleanups.forEach((cleanup) => cleanup?.());
             };
         });
     };
-    reference = (node) => {
-        // Keep the trigger's ARIA in sync whichever way it was rendered (snippet or Button).
-        // Only real controls carry aria-haspopup/aria-expanded; a wrapper div or a
-        // presentational span used as the anchor must not (axe: aria-allowed-attr).
-        const canCarryPopupState = node.matches(POPUP_CONTROL);
-        $effect(() => {
-            if (!canCarryPopupState)
+    /**
+     * A menu, listbox, tree or grid popup: its trigger's `aria-controls` points at the element
+     * carrying that role (not the wrapper), and that element is labelled by the trigger unless it
+     * has a name of its own. Ids it has to create are removed again when the panel goes.
+     */
+    #labelPopupOwner = (panel) => {
+        const haspopup = this.haspopup ?? 'dialog';
+        const role = haspopup === true ? 'menu' : POPUP_ROLE[haspopup];
+        const added = [];
+        const created = (element, name) => added.some(([e, n]) => e === element && n === name);
+        // Never replaces an attribute the consumer wrote; one this code wrote may be rewritten.
+        const set = (element, name, value) => {
+            if (element.hasAttribute(name) && !created(element, name))
+                return;
+            if (!created(element, name))
+                added.push([element, name]);
+            element.setAttribute(name, value);
+        };
+        const unset = (element, name) => {
+            if (!created(element, name))
                 return;
-            for (const [prop, value] of Object.entries(this.triggerProps)) {
-                const name = TRIGGER_ARIA[prop];
-                if (value === undefined)
-                    node.removeAttribute(name);
-                else
-                    node.setAttribute(name, String(value));
+            element.removeAttribute(name);
+            added.splice(added.findIndex(([e, n]) => e === element && n === name), 1);
+        };
+        let owner = null;
+        // Named by the consumer: `label` / `labelledBy` win over the trigger. Read reactively, so a
+        // name that changes while the popover is open reaches the role owner.
+        const name = () => {
+            // Read before the owner check, so the effect tracks them while no owner exists yet.
+            const { label, labelledBy } = this;
+            if (!owner)
+                return;
+            unset(owner, 'aria-label');
+            unset(owner, 'aria-labelledby');
+            if (labelledBy)
+                set(owner, 'aria-labelledby', labelledBy);
+            if (label)
+                set(owner, 'aria-label', label);
+            const trigger = this.triggerReference;
+            if (trigger && !owner.hasAttribute('aria-label') && !owner.hasAttribute('aria-labelledby')) {
+                set(trigger, 'id', `${this.id}-trigger`);
+                set(owner, 'aria-labelledby', trigger.id);
             }
+        };
+        const resolve = () => {
+            const next = panel.querySelector(`[role="${role}"]`);
+            if (next === owner)
+                return;
+            if (owner)
+                for (const attribute of ['aria-label', 'aria-labelledby'])
+                    unset(owner, attribute);
+            owner = next;
+            if (!owner) {
+                this.#popupOwnerId = null;
+                return;
+            }
+            set(owner, 'id', `${this.id}-${role}`);
+            this.#popupOwnerId = owner.id;
+            name();
+        };
+        $effect(name);
+        queueMicrotask(resolve);
+        const observer = typeof MutationObserver === 'undefined' ? null : new MutationObserver(resolve);
+        observer?.observe(panel, { childList: true, subtree: true });
+        return () => {
+            observer?.disconnect();
+            for (const [element, name] of added.splice(0))
+                element.removeAttribute(name);
+            this.#popupOwnerId = null;
+        };
+    };
+    /** Remembers a press on a trigger until its event has dispatched. */
+    #notePress = (node, event, reason) => {
+        const press = { node, event, reason };
+        this.#press = press;
+        setTimeout(() => {
+            if (this.#press === press)
+                this.#press = null;
+        });
+    };
+    reference = (node) => {
+        // Keep the trigger's ARIA in sync whichever way it was rendered (snippet or Button). With
+        // several triggers, only the one the panel is anchored to reads as expanded. Closed, they all
+        // read the same: the anchor is not read then, so attaching a trigger (a row of a long list
+        // sharing one popover) does not rewrite every other trigger's attributes.
+        $effect(() => {
+            const props = this.triggerProps;
+            const anchored = !props.expanded || this.triggerReference === node || this.triggerReference === null;
+            writePopupAria(node, {
+                ...props,
+                expanded: props.expanded && anchored,
+                controls: anchored ? props.controls : undefined
+            });
         });
         return untrack(() => {
-            this.triggerReference = node;
+            this.#triggers.set(node, ++this.#triggerSequence);
+            this.#recentTriggers.add(node);
+            queueMicrotask(() => this.#recentTriggers.delete(node));
+            this.#setLatestTrigger(node);
             // Gather all cleanup callbacks
             const cleanups = [];
-            cleanups.push(this.layer.node(node));
-            cleanups.push(this.safeArea.anchorReference?.(node));
+            // Inside the layer and anchoring the safe area while open; see `openSession`.
+            this.#currentSession?.addTrigger(node);
+            cleanups.push(() => this.#currentSession?.removeTrigger(node));
+            // Before the hover action's own listener, which may open at once (no delay).
+            cleanups.push(on(node, 'mouseenter', () => {
+                this.#hoveredTrigger = node;
+            }));
             cleanups.push(this.hoverAction.reference?.(node));
+            // Capture phase: these run before the element's own (delegated) handlers, so a
+            // `popover.toggle()` called from `onclick` knows the press it belongs to.
+            cleanups.push(on(node, 'pointerdown', (event) => {
+                this.#pointerType = event.pointerType;
+            }, { capture: true }));
+            const notePress = (event) => this.#notePress(node, event, 'trigger-press');
+            const noteKey = (event) => {
+                if (event.key === 'Enter' || event.key === ' ')
+                    this.#notePress(node, event, 'trigger-press');
+                else if (event.key === 'ArrowDown' || event.key === 'ArrowUp')
+                    this.#notePress(node, event, 'list-navigation');
+            };
+            node.addEventListener('click', notePress, true);
+            node.addEventListener('keydown', noteKey, true);
+            cleanups.push(() => {
+                node.removeEventListener('click', notePress, true);
+                node.removeEventListener('keydown', noteKey, true);
+            });
+            cleanups.push(this.#trackAnchorPoint(node));
             // Return combined cleanup function
             return () => {
                 cleanups.forEach((cleanup) => cleanup?.());
+                this.#triggers.delete(node);
+                this.#recentTriggers.delete(node);
+                if (this.#hoveredTrigger === node)
+                    this.#hoveredTrigger = null;
+                const wasActive = this.#activeTriggerNode === node;
+                const wasAnchor = wasActive || (!this.#activeTriggerNode && this.#latestTriggerNode === node);
+                if (wasActive)
+                    this.#setActiveTrigger(null);
+                if (this.#latestTriggerNode === node)
+                    this.#setLatestTrigger(this.#newestTrigger());
+                if (!wasAnchor)
+                    return;
+                // A trigger re-rendered as a new element (a re-rendered snippet, a responsive
+                // branch) attaches in the same flush: the panel moves to it. Only a trigger that
+                // is gone for good closes the popover instead of leaving it on a detached node.
+                const sequence = this.#triggerSequence;
+                const replacements = [...this.#recentTriggers];
+                queueMicrotask(() => {
+                    if (this.#destroyed || !this.isOpen)
+                        return;
+                    const successor = [...replacements, ...this.#triggersAfter(sequence)].find((candidate) => this.#triggers.has(candidate) && candidate.isConnected);
+                    if (successor) {
+                        if (wasActive)
+                            this.#setActiveTrigger(successor);
+                        return;
+                    }
+                    // The trigger that opened it is gone: another trigger does not inherit it.
+                    if (wasActive && !this.externalRef) {
+                        this.setOpen(false, { reason: 'trigger-unmount' });
+                        return;
+                    }
+                    this.#closeIfAnchorLost();
+                });
             };
         });
     };
+    #newestTrigger() {
+        let newest = null;
+        let newestSequence = -1;
+        for (const [node, sequence] of this.#triggers) {
+            if (sequence > newestSequence)
+                [newest, newestSequence] = [node, sequence];
+        }
+        return newest;
+    }
+    #triggersAfter(sequence) {
+        return [...this.#triggers].filter(([, at]) => at > sequence).map(([node]) => node);
+    }
     /**
-     * Makes any element a complete trigger: it anchors the panel (as \`reference\` does), toggles
-     * it on click when \`openOnClick\` allows, and keeps \`aria-expanded\` and friends in sync.
-     * An element that is not already a control also gets \`role="button"\`, \`tabindex="0"\` and
-     * Enter/Space activation, so a card or an avatar opens the panel from the keyboard too.
+     * Follows the pointer over the trigger while the popover is closed, so an open anchored to a
+     * line (`anchorTo: 'line'`) uses the line the pointer was on; the point stays put while open.
      */
-    trigger = (node) => {
-        const nativeControl = node.matches(NATIVE_CONTROL);
-        if (!node.matches(POPUP_CONTROL) && !node.hasAttribute('role')) {
-            node.setAttribute('role', 'button');
-        }
-        if (!nativeControl && !node.hasAttribute('tabindex'))
-            node.tabIndex = 0;
-        // The element's own handler wins. One that still opens, closes or toggles the popover
-        // (`onclick={popover.toggle}` kept from before this attachment existed) has acted by the
-        // time the event finishes dispatching, so the default toggle waits until then and runs only
-        // if nothing asked for an open state meanwhile; toggling regardless would undo that call.
-        let pending;
-        const activate = () => {
-            if (!this.openOnClick)
+    #trackAnchorPoint = (node) => {
+        const follow = (event) => {
+            const reference = this.referenceElement;
+            if (this.isOpen || !reference)
                 return;
-            const requests = this.#openRequests;
-            clearTimeout(pending);
-            pending = setTimeout(() => {
-                if (this.#openRequests === requests)
-                    this.toggle();
-            });
+            const rect = reference.getBoundingClientRect();
+            this.#anchorOffset = {
+                reference,
+                dx: event.clientX - rect.left,
+                dy: event.clientY - rect.top
+            };
         };
-        const onKeydown = (event) => {
-            if (nativeControl || event.target !== node)
-                return;
-            if (event.key !== 'Enter' && event.key !== ' ')
-                return;
-            event.preventDefault();
-            activate();
+        // A finger lifts (pointerleave) before the click that opens the popover: keep its point.
+        const forget = (event) => {
+            if (!this.isOpen && event.pointerType !== 'touch')
+                this.#anchorOffset = null;
+        };
+        // A keyboard open has no pointer: it takes the first or last line, not a stale hover point.
+        const forgetOnKey = () => {
+            if (!this.isOpen)
+                this.#anchorOffset = null;
+        };
+        node.addEventListener('pointerenter', follow);
+        node.addEventListener('pointermove', follow);
+        node.addEventListener('pointerdown', follow);
+        node.addEventListener('pointerleave', forget);
+        node.addEventListener('keydown', forgetOnKey);
+        return () => {
+            node.removeEventListener('pointerenter', follow);
+            node.removeEventListener('pointermove', follow);
+            node.removeEventListener('pointerdown', follow);
+            node.removeEventListener('pointerleave', forget);
+            node.removeEventListener('keydown', forgetOnKey);
+        };
+    };
+    /** Attachment for the arrow element inside the panel; see the `arrow` prop. */
+    arrowRef = (node) => {
+        this.arrowElement = node;
+        return () => {
+            if (this.arrowElement === node)
+                this.arrowElement = null;
+        };
+    };
+    /** Payload getters of the triggers made with `triggerFor`. */
+    // eslint-disable-next-line svelte/prefer-svelte-reactivity -- teardown bookkeeping; `#payloadVersion` carries the reactivity
+    #payloads = new Map();
+    #payloadVersion = $state(0);
+    /**
+     * The payload of the trigger the panel is anchored to: the one that opened it, else the most
+     * recently attached. `undefined` for a trigger made without one. Several triggers share this one
+     * popup, so a list of rows needs a single popover, not one per row.
+     */
+    payload = $derived.by(() => {
+        void this.#payloadVersion;
+        const trigger = this.triggerReference;
+        return trigger ? this.#payloads.get(trigger)?.() : undefined;
+    });
+    /**
+     * A complete trigger (see `trigger`) that carries data for the panel: read it back as
+     * `popover.payload` while this trigger is the one the panel is anchored to. Pass a getter, so
+     * the payload follows its source without re-attaching the trigger:
+     * `{@attach popover.triggerFor(() => row)}`.
+     */
+    triggerFor(payload) {
+        return (node) => {
+            const attached = this.trigger(node);
+            untrack(() => {
+                this.#payloads.set(node, payload);
+                this.#payloadVersion += 1;
+            });
+            return () => {
+                attached?.();
+                untrack(() => {
+                    if (this.#payloads.get(node) !== payload)
+                        return;
+                    this.#payloads.delete(node);
+                    this.#payloadVersion += 1;
+                });
+            };
         };
-        node.addEventListener('click', activate);
-        node.addEventListener('keydown', onKeydown);
+    }
+    /**
+     * Makes any element a complete trigger: it anchors the panel (as `reference` does), toggles
+     * it on click when `openOnClick` allows, and keeps `aria-expanded` and friends in sync.
+     * An element that is not already a control also gets `role="button"`, `tabindex="0"` and
+     * Enter/Space activation, so a card or an avatar opens the panel from the keyboard too.
+     * The element's own handler runs first: calling `event.preventDefault()` there, or opening,
+     * closing or toggling the popover itself, stops the default toggle.
+     */
+    trigger = (node) => {
+        const offActivation = triggerActivation(node, {
+            enabled: () => this.openOnClick,
+            requests: () => this.#openRequests,
+            activate: (event) => this.toggle({ reason: 'trigger-press', event, trigger: node })
+        });
         const offReference = this.reference(node);
         return () => {
-            clearTimeout(pending);
-            node.removeEventListener('click', activate);
-            node.removeEventListener('keydown', onKeydown);
+            offActivation();
             offReference?.();
         };
     };
 }
-// Use interface merging to add the properties
+/**
+ * The state behind the `PopoverApi` a Popover hands its snippets and callbacks. For library
+ * components that drive a popover's internals (menus, hover cards); consumers get the narrow API.
+ */
+export const popoverInternals = (popover) => popover;
 export const usePopoverContext = () => {
     const hasPopover = hasContext('popover');
     if (!hasPopover) {