/**
 * Resolve the root a node's styles should live in.
 *
 * Returns the node's `ShadowRoot` when it (or an ancestor) is shadowed, the
 * owning `Document` otherwise. A `<style>` placed in this root reaches the node
 * regardless of whether the widget runs in light or shadow DOM. For a detached
 * node (one not yet mounted) this falls back to the owning document.
 */
declare function getStyleRoot(node: Node): Document | ShadowRoot;
/**
 * Inject a plugin's CSS once into the correct root: the widget's shadow root
 * when shadowed, the document head otherwise. Idempotent: keyed by `id`, so it
 * is safe to call on every render.
 *
 * Pass the element you're about to return from a render hook. While building, an
 * element is detached and its eventual root is unknown, so this injects into the
 * owning document immediately (covering the default light-DOM case with no
 * flash) and then, on the next microtask: after the widget has mounted the
 * element: re-resolves and also injects into its shadow root if it landed in
 * one. You may also pass an explicit `Document` or `ShadowRoot`.
 *
 * @example
 * ```ts
 * renderApproval: ({ message, approve, deny }) => {
 *   const card = buildCard(message.approval, approve, deny);
 *   injectStyles(card, "my-approval-plugin", CSS);
 *   return card;
 * }
 * ```
 */
declare function injectStyles(target: Node | Document | ShadowRoot, id: string, css: string): void;
type PopoverPlacement = "bottom-start" | "bottom-end" | "top-start" | "top-end";
interface PopoverOptions {
    /** Element the popover is positioned against. */
    anchor: HTMLElement;
    /** The floating element (menu, tooltip, panel). Built detached; mounted on `open`. */
    content: HTMLElement;
    /** Where to place `content` relative to `anchor`. Default `"bottom-start"`. */
    placement?: PopoverPlacement;
    /** Gap in px between anchor and content. Default `6`. */
    offset?: number;
    /** Set `content`'s `min-width` to the anchor's width. Default `false`. */
    matchAnchorWidth?: boolean;
    /**
     * Inline `z-index` for `content`. Default `2147483000` so it overlays the rest
     * of the widget. Pass `null` to leave z-index to your own CSS.
     */
    zIndex?: number | null;
    /**
     * Where to mount `content`. Defaults to the anchor's shadow root (when
     * shadowed) or `document.body`: keeping it inside the same style + stacking
     * scope as the anchor while escaping the transcript's scroll clipping.
     */
    container?: HTMLElement | ShadowRoot;
    onOpen?: () => void;
    /** Fired when the popover closes by itself (outside click or the anchor leaving the DOM). */
    onDismiss?: (reason: "outside" | "anchor-removed") => void;
}
interface PopoverHandle {
    readonly isOpen: boolean;
    open(): void;
    close(): void;
    toggle(): void;
    /** Recompute position from the current anchor rect (called automatically on scroll/resize). */
    reposition(): void;
    /** Close and release all listeners; the handle is inert afterward. */
    destroy(): void;
}
/**
 * A floating popover anchored to an element: `fixed`-positioned (so it overlays
 * the rest of the widget and isn't clipped by scroll containers), dismissed on
 * outside pointerdown, repositioned on scroll/resize, and auto-closed if the
 * anchor leaves the DOM. Mount your styles with {@link injectStyles}.
 *
 * @example
 * ```ts
 * const popover = createPopover({
 *   anchor: splitButton,
 *   content: menu,
 *   placement: "bottom-start",
 *   matchAnchorWidth: true,
 * });
 * caret.addEventListener("click", () => popover.toggle());
 * // on teardown: popover.destroy();
 * ```
 */
declare function createPopover(options: PopoverOptions): PopoverHandle;
/**
 * Whether an event originated from an editable element (`<input>`, `<textarea>`,
 * or `contenteditable`). Use it to avoid hijacking keys like Enter/Escape while
 * the user is typing in the composer.
 *
 * Inspects the composed path, so it works for events that cross the widget's
 * Shadow-DOM boundary (where `event.target` is retargeted to the host).
 */
declare function isEditableEventTarget(event: Event): boolean;

export { type PopoverHandle, type PopoverOptions, type PopoverPlacement, createPopover, getStyleRoot, injectStyles, isEditableEventTarget };