entasis 0.10.2 → 0.12.0

package/dist/components/Popover/popover.props.d.ts

@@ -1,25 +1,64 @@
 import type { Snippet } from 'svelte';
-import type { PopoverState } from './popover.state.svelte.js';
+import type { PopoverApi } from './popover.api.js';
 import type { ResponsiveProps } from '../Theme/theme.js';
 import type { Sizes } from '../../types/theme.js';
 import type { ButtonProps } from '../Button/index.js';
 import type { FSOProps } from '../../transitions/transition.js';
-import { type Placement, type VirtualElement } from '@floating-ui/dom';
+import { type Alignment, type Placement, type VirtualElement } from '@floating-ui/dom';
 import type { WithAttachments } from '../../types/props.js';
+import type { PopupPlacementSide } from '../../utils/stateAttributes.js';
 import type { PopoverThemeProps } from './popover.theme.js';
-export type PopoverProps = WithAttachments<{
+import type { OpenChangeHandler } from '../../utils/openChange.js';
+import type { FocusOnClose } from '../../utils/useFocusScope.svelte.js';
+/**
+ * How an open popover was opened: `hover` (the pointer rested on the trigger), `press` (a click
+ * or tap on the trigger), `keyboard` (Enter, Space or an arrow key on the trigger), or
+ * `programmatic` (`open()` from code, the `open` prop, `defaultOpen`).
+ */
+export type PopoverOpenReason = 'hover' | 'press' | 'keyboard' | 'programmatic';
+/**
+ * A side named by reading direction: `inline-start` is the left side in a left-to-right document
+ * and the right side in a right-to-left one; `inline-end` is the other.
+ */
+export type PopoverLogicalSide = 'inline-start' | 'inline-end';
+/**
+ * Where the panel goes relative to its reference: a floating-ui placement (`bottom-start`), or a
+ * logical side with an optional alignment (`inline-end`, `inline-end-start`). The `start` / `end`
+ * alignment of `top` and `bottom` already follows the reading direction.
+ */
+export type PopoverPlacement = Placement | PopoverLogicalSide | `${PopoverLogicalSide}-${Alignment}`;
+/**
+ * The side a placed panel sits on, written as `data-side` on the panel and `data-popup-side` on
+ * its trigger: the physical side, the logical one when a logical side was requested, or `none`
+ * when `positionPanel` placed the panel.
+ */
+export type PopoverSide = PopupPlacementSide;
+/** The viewport `shift` keeps a floating panel inside; see `collisionBoundary`. */
+export type PopoverCollisionBoundary = 'visualViewport' | 'layoutViewport';
+/** Perpendicular sides a panel falls back to; see `fallbackAxisSide`. */
+export type PopoverFallbackAxisSide = 'start' | 'end' | 'none';
+/** What a panel anchors to on a reference that wraps across lines; see `anchorTo`. */
+export type PopoverAnchorTo = 'box' | 'line';
+export type PopoverProps<Payload = unknown> = WithAttachments<{
     /** Stable DOM id for the popover dialog; falls back to a generated id when omitted. */
     id?: string;
     /** Controls whether the popover is open; bindable for two-way control. */
     open?: boolean;
     /** Initial open state when `open` is not provided. */
     defaultOpen?: boolean;
-    /** Called once when the library requests an open-state change. */
-    onOpenChange?: (open: boolean) => void;
-    /** Called after the open transition finishes. */
-    onAfterOpen?: (payload: PopoverState) => void;
-    /** Called after the close transition finishes. */
-    onAfterClose?: (payload: PopoverState) => void;
+    /**
+     * Called before the popover opens or closes, with the requested state and the change details:
+     * `reason` (`'trigger-press'`, `'trigger-hover'`, `'outside-press'`, `'escape-key'`,
+     * `'trigger-unmount'`, `'imperative-action'`…), the originating `event`, the `trigger`
+     * element, the `interaction` type and `cancel()`. Calling `details.cancel()` keeps the popover
+     * as it is and leaves the event untouched. Inside the callback, `open` still holds the
+     * previous state.
+     */
+    onOpenChange?: OpenChangeHandler;
+    /** Called once per open, after the open transition finishes (right away when none plays, e.g. `defaultOpen`). */
+    onAfterOpen?: (payload: PopoverApi<Payload>) => void;
+    /** Called once per close, after the close transition finishes. */
+    onAfterClose?: (payload: PopoverApi<Payload>) => void;
     /** Popover panel size variant; supports responsive values. */
     size?: ResponsiveProps<Sizes>;
     /** Gap in pixels between the reference element and the popover panel. */
@@ -28,11 +67,43 @@ export type PopoverProps = WithAttachments<{
      * External positioning reference instead of the built-in trigger. An HTMLElement, or a
      * floating-ui virtual element — an object with `getBoundingClientRect()` returning a rect at a
      * point, e.g. `{ getBoundingClientRect: () => new DOMRect(x, y, 0, 0) }` to anchor a context
-     * menu at the cursor.
+     * menu at the cursor. An open popover closes when this element leaves the document.
      */
     ref?: HTMLElement | VirtualElement | null;
-    /** Preferred placement relative to the reference element; supports responsive values. */
-    position?: ResponsiveProps<Placement>;
+    /**
+     * Preferred placement relative to the reference element; supports responsive values. Takes a
+     * floating-ui placement (`bottom-start`) or a logical side (`inline-end`, `inline-end-start`)
+     * that resolves with the reading direction. The panel flips to the opposite side when the
+     * preferred one has no room; the side it lands on is written as `data-side`.
+     */
+    position?: ResponsiveProps<PopoverPlacement>;
+    /**
+     * The viewport the panel is shifted back into when it would cross an edge. `'visualViewport'`
+     * is the visible area, which shrinks under an on-screen keyboard and follows pinch-zoom;
+     * `'layoutViewport'` ignores pinch-zoom, so panning a zoomed page doesn't drag the panel
+     * along. Flipping and the `--available-*` sizes always use the visual viewport. ContextMenu
+     * uses `'layoutViewport'`.
+     * @default 'visualViewport'
+     */
+    collisionBoundary?: PopoverCollisionBoundary;
+    /**
+     * When the panel fits neither on its side nor on the opposite one, also try the perpendicular
+     * axis: `'end'` tries bottom (or the inline end) first, `'start'` top (or the inline start),
+     * `'none'` stays on the axis. A panel placed beside its reference (left or right) tries only
+     * the side asked for, so it never jumps over the reference's own row and menu. Submenus use
+     * `'end'`: a submenu with no room beside its menu opens below its row, sliding back into the
+     * viewport if that is still too tight.
+     * @default 'none'
+     */
+    fallbackAxisSide?: PopoverFallbackAxisSide;
+    /**
+     * What the panel anchors to when its reference wraps across lines (a link in prose): `'box'`
+     * is the whole bounding box; `'line'` is the line the pointer was on when the panel opened,
+     * kept while it stays open. Without a pointer (a keyboard open) the panel takes the first
+     * line above the reference and the last line below it.
+     * @default 'box'
+     */
+    anchorTo?: PopoverAnchorTo;
     /**
      * Places the panel yourself instead of floating-ui: return its viewport coordinates (the
      * panel is `position: fixed`) and optionally a `minWidth` in px that replaces `fitTrigger`'s,
@@ -51,42 +122,126 @@ export type PopoverProps = WithAttachments<{
     } | null;
     /** When true, clicking the trigger toggles the popover open and closed. */
     openOnClick?: boolean;
-    /** When true, hovering the trigger opens the popover after `delay`. */
+    /**
+     * When true, hovering the trigger opens the popover after `delay`, including one that started
+     * open. A hover-opened popover does not lock page scroll; pressing its trigger pins it open.
+     * Touch taps and disabled triggers never hover-open it, and a trigger that appears under a
+     * resting pointer waits for the pointer to move. Right after another hover popover, tooltip
+     * or hover card was open, a root popover opens without the delay.
+     */
     openOnHover?: boolean;
-    /** Delay in milliseconds before opening on hover when `openOnHover` is enabled. */
+    /**
+     * Delay in milliseconds before opening on hover when `openOnHover` is enabled. Default `100`.
+     * Leaving the trigger, or any other open or close meanwhile, cancels the pending open.
+     */
     delay?: number;
+    /**
+     * Milliseconds the pointer may spend outside the hover safe area before `closeOnMouseLeave`
+     * closes the popover. A longer delay forgives a pointer that overshoots on its way to the
+     * panel. Default `120`.
+     */
+    closeDelay?: number;
     /** When true, enter and exit transitions slide from the placement direction. */
     directedTransition?: boolean;
     /** Fly/scale opacity transition overrides for open and close; supports responsive values. */
     transition?: ResponsiveProps<FSOProps>;
-    /** Snippet for popover panel content; receives the popover state instance. */
-    children?: Snippet<[PopoverState]>;
-    /** Snippet, button props, or `false` to render, customize, or hide the trigger control. */
-    trigger?: Snippet<[PopoverState]> | (ButtonProps & {
+    /** Snippet for popover panel content; receives the popover (`PopoverApi`). */
+    children?: Snippet<[PopoverApi<Payload>]>;
+    /**
+     * Snippet, button props, or `false` to render, customize, or hide the trigger control. The
+     * trigger that opened the popover anchors it and gets focus back; an open popover closes when
+     * that trigger unmounts (`reason: 'trigger-unmount'`), and a trigger re-rendered as a new
+     * element keeps it open. The built-in button's `onclick` runs first: calling
+     * `event.preventDefault()` there stops the toggle.
+     */
+    trigger?: Snippet<[PopoverApi<Payload>]> | (ButtonProps & {
         content?: string;
     }) | false;
     /**
      * Where focus goes when the panel opens: `'first'` (autofocus target or first tabbable),
-     * `'container'` (the panel itself), or `false` (stay on the trigger). Focus always returns
-     * to the trigger when the popover closes.
+     * `'container'` (the panel itself), or `false` (stay on the trigger). When the popover
+     * closes, focus returns to the trigger that opened it, or after a programmatic open to the
+     * element that had focus when it opened. A `modal` popover defaults to `'first'`.
      * @default false
      */
     focusOnOpen?: 'first' | 'container' | false;
+    /**
+     * Where focus goes when the popover closes with focus inside it or after a trigger opened it.
+     * By default it returns to the trigger (with a visible focus ring after Escape or another
+     * keyboard close); when that control is gone or disabled, to the most recent element that is
+     * still on the page. `false` leaves focus where it is, an element receives it, and a function
+     * is called with the change details (`reason`, `interaction`…) and returns one of these, or
+     * nothing to restore as usual. A close because focus moved on (`'focus-out'`) never moves it.
+     * @default true
+     */
+    focusOnClose?: FocusOnClose;
     /**
      * Value of `aria-haspopup` applied to the trigger, describing what the panel contains.
-     * `aria-expanded` and `aria-controls` are managed automatically alongside it.
+     * `aria-expanded` and `aria-controls` are managed automatically alongside it. A `'dialog'`
+     * popup renders in a `<dialog>`; any other value renders a plain wrapper, points
+     * `aria-controls` at the element inside with the matching role (`role="menu"` for `menu` and
+     * `true`) and labels that element by the trigger unless it has an `aria-label`.
      * @default 'dialog'
      */
     haspopup?: 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid' | true;
-    /** When true, clicking outside the popover closes it. */
+    /**
+     * The popup's accessible name, written as `aria-label` on the `<dialog>` (on the menu, listbox,
+     * tree or grid element inside a non-dialog popup, unless it has a name of its own, and on the
+     * mobile sheet's dialog). A popover that holds a form or a picker is announced as a dialog:
+     * name it, or point `labelledBy` at its visible heading.
+     */
+    label?: string;
+    /**
+     * The id of an element that names the popup, written as `aria-labelledby` where `label` goes.
+     * Wins over `label` for assistive technology when both are set.
+     */
+    labelledBy?: string;
+    /**
+     * Makes the popover modal while it floats: Tab stays inside the panel, the rest of the page
+     * becomes `inert`, the panel opens with focus inside it (`focusOnOpen` defaults to
+     * `'first'`), and a visually hidden Close button at the end of the panel gives screen reader
+     * users a control that closes it. A modal popover does not open on hover. The mobile sheet is
+     * always modal; an `inline` panel ignores this.
+     * @default false
+     */
+    modal?: boolean;
+    /**
+     * Bridges Tab between the trigger and the panel, which is portaled to the end of the page:
+     * Tab on the open trigger enters the panel, Tab past its last control continues after the
+     * trigger and closes it, and Shift+Tab on its first control returns to the trigger. Applies to
+     * dialog popups opened from a trigger; menus, listboxes and the like (`haspopup`) and modal
+     * popovers manage Tab themselves. Turn it off for a panel that is not meant to be tabbed into.
+     * @default true
+     */
+    tabBridge?: boolean;
+    /**
+     * Closes the popover (`reason: 'focus-out'`) when focus that was inside it or on its trigger
+     * moves to a control outside both and outside any popup opened from it. Defaults to the value
+     * of `closeOnClickOutside`, so a popover that outlives outside presses outlives focus moving
+     * on too. Does not apply to menus, listboxes and the like, or to a popover the pointer opened
+     * by hovering.
+     */
+    closeOnFocusOut?: boolean;
+    /**
+     * Draws an arrow from the panel toward its trigger. It is placed with floating-ui's `arrow`
+     * middleware, so it stays on the trigger when the panel shifts to fit the viewport, and
+     * reports the side it sits on as `data-side` (`data-uncentered` when the trigger is not
+     * under its middle). Style it with `theme.arrow`. Only a floating panel has one.
+     * @default false
+     */
+    arrow?: boolean;
+    /** When true, pressing outside the popover closes it. A press that began before it opened does not count, and on touch screens only a tap does (a finger that starts scrolling the page does not). */
     closeOnClickOutside?: boolean;
     /** When true, pressing Escape closes the topmost open popover. */
     closeOnEscape?: boolean;
-    /** When true, moving the pointer outside the hover safe area closes the popover. The safe area is the trigger, the panel, and a prediction cone toward the panel, so a diagonal move to the panel keeps it open. */
+    /** When true, moving the pointer outside the hover safe area closes a popover that hovering opened. The safe area is the trigger, the panel, and a prediction cone toward the panel, so a diagonal move to the panel keeps it open. A popover opened by a press, the keyboard or code stays open. */
     closeOnMouseLeave?: boolean;
     /** When true, renders debug overlays for the hover safe-area rectangles (blue) and the prediction cone toward the panel (orange). */
     debugSafeArea?: boolean;
-    /** When true, locks page scroll while a root-level popover is open. */
+    /**
+     * When true, locks page scroll while a root-level popover is open, unless hovering opened it or
+     * a finger did and the panel is narrower than the viewport (the page still scrolls under it).
+     */
     lockScroll?: boolean;
     /** Additional CSS classes merged onto the popover dialog element. */
     class?: string;

package/dist/components/Popover/popover.state.svelte.d.ts

@@ -1,77 +1,209 @@
-import type { PopoverProps } from './popover.props.js';
-import { type Placement, type VirtualElement } from '@floating-ui/dom';
+import type { PopoverOpenReason, PopoverProps } from './popover.props.js';
+import type { Placement, VirtualElement } from '@floating-ui/dom';
+import { type LayerHandle } from '../../utils/layers.svelte.js';
+import type { Attachment } from 'svelte/attachments';
+import { useSafeArea } from '../../utils/safeArea.svelte.js';
+import { type OpenLifecycle } from '../../utils/openLifecycle.svelte.js';
+import { type OpenChangeDetails, type OpenChangeInit } from '../../utils/openChange.js';
+import { type PopupTriggerProps } from '../../utils/trigger.js';
 import { type PopoverThemeProps } from './popover.theme.js';
+import type { PopoverApi } from './popover.api.js';
+import { type PanelDirection, type PanelPlacement } from './popover.position.js';
+/** Where a floating panel was last placed; see `PopoverState.placement`. */
+export type PopoverPlacementState = Pick<PanelPlacement, 'side' | 'align' | 'anchorHidden'>;
 type MakeRequired<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
-interface PopoverOptions extends MakeRequired<Pick<PopoverProps, 'id' | 'size' | 'position' | 'transition' | 'onOpenChange' | 'offset' | 'directedTransition' | 'closeOnEscape' | 'lockScroll' | 'closeOnMouseLeave' | 'debugSafeArea' | 'closeOnClickOutside' | 'openOnHover' | 'delay' | 'openOnClick' | 'mobileSheet' | 'inline' | 'focusOnOpen' | 'haspopup' | 'positionPanel'>, 'directedTransition' | 'closeOnEscape' | 'lockScroll' | 'closeOnMouseLeave' | 'debugSafeArea' | 'closeOnClickOutside' | 'openOnHover' | 'delay' | 'openOnClick' | 'inline'> {
+interface PopoverOptions<Payload = unknown> extends MakeRequired<Pick<PopoverProps<Payload>, 'id' | 'size' | 'position' | 'transition' | 'onOpenChange' | 'onAfterOpen' | 'onAfterClose' | 'offset' | 'directedTransition' | 'closeOnEscape' | 'lockScroll' | 'closeOnMouseLeave' | 'debugSafeArea' | 'closeOnClickOutside' | 'openOnHover' | 'delay' | 'closeDelay' | 'openOnClick' | 'mobileSheet' | 'inline' | 'focusOnOpen' | 'focusOnClose' | 'haspopup' | 'positionPanel' | 'collisionBoundary' | 'fallbackAxisSide' | 'anchorTo' | 'modal' | 'label' | 'labelledBy' | 'tabBridge' | 'closeOnFocusOut' | 'arrow'>, 'id' | 'directedTransition' | 'closeOnEscape' | 'lockScroll' | 'closeOnMouseLeave' | 'debugSafeArea' | 'closeOnClickOutside' | 'openOnHover' | 'delay' | 'openOnClick' | 'inline' | 'modal' | 'tabBridge' | 'arrow'> {
     isOpen: boolean;
     externalRef?: HTMLElement | VirtualElement | null;
     fitTrigger: boolean;
     /** The instance `theme.motion` slot; the `transition` prop still wins over it. */
     motion?: PopoverThemeProps['motion'];
 }
-declare const PopoverOptionsBase: new () => PopoverOptions;
-export declare class PopoverState extends PopoverOptionsBase {
+/** What `open`, `close`, `toggle` and `setOpen` accept: details, a partial, or the DOM event. */
+export type PopoverOpenChangeInput = OpenChangeDetails | OpenChangeInit | Event;
+declare const PopoverOptionsBase: new <Payload>() => PopoverOptions<Payload>;
+/** The part of the safe area a popover's owners read: whether a point is in it, and a refresh. */
+export type PopoverSafeArea = Pick<ReturnType<typeof useSafeArea>, 'containsPoint' | 'updateAreas'>;
+export declare class PopoverState<Payload = unknown> extends PopoverOptionsBase<Payload> implements PopoverApi<Payload> {
     #private;
+    /** The trigger that opened the popover, while it is open; `null` for a programmatic open. */
+    activeTrigger: HTMLElement | null;
+    /**
+     * The trigger the panel anchors to: the one that opened it, else the most recently attached
+     * `reference` / `trigger` element.
+     */
     triggerReference: HTMLElement | null;
     referenceElement: HTMLElement | VirtualElement | null;
     dialogElement: HTMLElement | null;
+    /** The arrow inside the panel (`arrow`); `null` while there is none. */
+    arrowElement: HTMLElement | null;
+    /** The panel element focus moves into (inside `dialogElement`); `null` while it is not mounted. */
+    panelElement: HTMLElement | null;
     transformOrigin: string;
     triggerWidth: number | null;
-    parent: PopoverState | null;
+    /**
+     * How the popover was opened: `hover`, `press` (pointer), `keyboard`, or `programmatic`
+     * (`open()` from code, the `open` prop, `defaultOpen`). `null` once closed.
+     */
+    openReason: PopoverOpenReason | null;
+    /** The details of the last change that was applied, kept until the next one. */
+    lastOpenChange: OpenChangeDetails | null;
+    /**
+     * 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: PopoverPlacementState | 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: {
+        'data-side': import("../../utils/stateAttributes.js").PopupPlacementSide | undefined;
+        'data-align': import("../../utils/stateAttributes.js").PopupAlign | undefined;
+        'data-anchor-hidden': import("../../utils/stateAttributes.js").Presence;
+        'data-entering': import("../../utils/stateAttributes.js").Presence;
+        'data-exiting': import("../../utils/stateAttributes.js").Presence;
+        'data-open': import("../../utils/stateAttributes.js").Presence;
+        'data-closed': import("../../utils/stateAttributes.js").Presence;
+    };
+    parent: PopoverState<unknown> | null;
     get children(): readonly PopoverState[];
     hasChildOpen: boolean;
-    hasTransitioned: boolean;
     theme: import("../Theme/theme.state.svelte.js").ThemeState;
-    layer: import("../../utils/layers.svelte.js").LayerHandle;
+    /**
+     * 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: OpenLifecycle;
+    /** Where the panel is in its open/close lifecycle; see `PopoverApi.status`. */
+    get status(): import("../../utils/stateAttributes.js").OpenTransitionStatus;
+    /** @deprecated Read `status === 'open'`; kept for one minor. */
+    get hasTransitioned(): boolean;
+    /** The popover's layer while it is open or closing, else `null`. */
+    get layer(): LayerHandle | 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(): boolean;
+    /**
+     * 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(): PopoverSafeArea;
     computedSize: import("../../types/theme.js").Sizes;
     isMobileSheet: boolean;
     computedMode: 'floating' | 'inline' | 'mobileSheet';
+    /**
+     * 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: boolean;
+    /**
+     * 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: boolean;
+    /** The id of the element `aria-controls` points at while open. */
+    controlsId: string;
     /**
      * 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.
      */
-    triggerProps: {
-        haspopup: true | "dialog" | "menu" | "listbox" | "tree" | "grid";
-        expanded: boolean;
-        controls: string | undefined;
-    };
-    focusScope: {
-        attachment: (target: HTMLElement) => () => void;
-        restore: () => void;
-    };
+    triggerProps: PopupTriggerProps;
+    /**
+     * 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(): boolean;
+    /**
+     * 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(): boolean;
     private resolveMotion;
     computedTransition: import("../../utils/motion/index.js").ResolvedMotion;
-    computedPosition: Placement;
-    safeArea: {
-        reference: (ref: HTMLElement) => () => void;
-        anchorReference: (ref: HTMLElement) => () => void;
-        floatingReference: (ref: HTMLElement) => () => void;
-        updateAreas: () => void;
-        containsPoint: (x: number, y: number) => boolean;
-    };
+    computedPosition: import("./popover.props.js").PopoverPlacement;
     hoverAction: {
-        reference: (ref: HTMLElement) => (() => void) | null;
+        reference: (ref: HTMLElement) => () => void;
         destroy: () => void;
+        cancel: () => void;
         readonly isHovered: boolean;
     };
     addChild: (child: PopoverState) => () => () => void;
-    constructor(options: PopoverOptions);
-    toggle: () => void;
-    open: () => void;
-    close: () => void;
-    setOpen: (nextOpen: boolean) => void;
-    applyDirectedTransition: (node: HTMLElement, placement: Placement) => void;
+    constructor(options: PopoverOptions<Payload>);
+    /**
+     * 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(): boolean;
+    /**
+     * 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: () => void;
+    /** Toggles the popover. A press on the trigger of a popover the pointer opened by hovering pins it open instead. */
+    toggle: (input?: PopoverOpenChangeInput) => void;
+    open: (input?: PopoverOpenChangeInput) => void;
+    /** Closes the popover. Returns `false` when `onOpenChange` cancelled the change. */
+    close: (input?: PopoverOpenChangeInput) => boolean;
+    /**
+     * 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: boolean, input?: PopoverOpenChangeInput) => boolean;
+    /**
+     * 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: Placement, { direction, intro }?: {
+        direction?: PanelDirection;
+        intro?: boolean;
+    }) => void;
+    /** Places the floating panel against its reference once; see `PanelPositioner.place`. */
     place: (node: HTMLElement, mount?: boolean) => Promise<void>;
-    dialog: (node: HTMLDialogElement) => () => void;
+    /** Attachment for the positioning wrapper (`<dialog>`, or a `<div>` for a non-dialog popup). */
+    dialog: (node: HTMLElement) => () => void;
     panel: (node: HTMLElement) => () => void;
     reference: (node: HTMLElement) => () => void;
+    /** Attachment for the arrow element inside the panel; see the `arrow` prop. */
+    arrowRef: (node: HTMLElement) => () => void;
+    /**
+     * 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: Payload | 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: () => Payload): Attachment<HTMLElement>;
     /**
-     * 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
+     * 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: HTMLElement) => () => void;
 }
-export declare const usePopoverContext: () => PopoverState | null;
+/**
+ * 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 declare const popoverInternals: <Payload = unknown>(popover: PopoverApi<Payload>) => PopoverState<Payload>;
+export declare const usePopoverContext: () => PopoverState<unknown> | null;
 export {};