import { AgentxService } from "../internal-types";
import { createJsApiLogger } from "./common/_logger";
import { createServiceChecker } from "./common/_service-checker";
/**
 * Desktop.popover JS API — see widget-iframe-shell README §"Popovers" for the
 * full architecture, dismiss-behaviour table, and iframe-nesting limitations.
 *
 * Calls forward to AGENTX_SERVICE.popover (the shim seeded by the iframe
 * shell). When the widget runs outside an iframe shell the shim is absent
 * and every method becomes a logged no-op.
 */
export type PopoverPlacement = "top-start" | "top" | "top-end" | "bottom-start" | "bottom" | "bottom-end" | "left-start" | "left" | "left-end" | "right-start" | "right" | "right-end";
export interface PopoverPanelConfig {
    /** CSS width of the popover iframe. Default "350px". */
    width?: string;
    /** CSS height of the popover iframe. Default "auto". */
    height?: string;
    /** CSS max-height of the popover iframe; also clamped by viewport. Default "500px". */
    maxHeight?: string;
    /** md-popover placement. Auto-flips when there is not enough space. Default "bottom-start". */
    placement?: PopoverPlacement;
    /** Pixel offset between trigger and popover. Default 4. */
    offset?: number;
}
/**
 * Dismiss-trigger configuration. Defaults and the full table of dismiss
 * sources covered by each flag are documented in widget-iframe-shell README
 * §"Defaults & behavior" and §"Dismiss behaviour".
 */
export interface PopoverDismissOn {
    /** Default `true`. */
    outsideClick?: boolean;
    /** Default `true`. */
    escape?: boolean;
    /** Default `false` — host viewport resize is handled by md-popover's autoUpdate. */
    windowResize?: boolean;
    /** Default `false`. */
    windowBlur?: boolean;
}
export type PopoverAttributeValue = string | number | boolean | null;
/**
 * Trigger element rect in iframe-local viewport coordinates (the values
 * returned by `Element.getBoundingClientRect()` from inside the widget's
 * iframe). See widget-iframe-shell README §"Trigger anchoring".
 */
export interface PopoverTriggerRect {
    x: number;
    y: number;
    width: number;
    height: number;
}
export interface PopoverOpenOptions {
    /** Custom element tag name to render inside the popover iframe. */
    comp: string;
    /** Bundle URL for the popover content. May differ from the trigger bundle. */
    script: string;
    panel?: PopoverPanelConfig;
    attributes?: Record<string, PopoverAttributeValue>;
    properties?: Record<string, unknown>;
    dismissOn?: PopoverDismissOn;
    /**
     * Anchor the popover to a specific element inside the trigger iframe by
     * passing its `getBoundingClientRect()`. Omit to anchor to the whole
     * iframe. See widget-iframe-shell README §"Trigger anchoring".
     */
    trigger?: {
        rect: PopoverTriggerRect;
    };
}
export interface PopoverResizeDimensions {
    width?: string;
    height?: string;
    maxHeight?: string;
}
export interface PopoverLifecycleEvent {
    type: "open" | "close";
    popoverId: string;
}
type Config = {
    logger: ReturnType<typeof createJsApiLogger>;
    serviceChecker: ReturnType<typeof createServiceChecker>;
};
/**
 * `Desktop.popover` SDK surface — see widget-iframe-shell README §"Popovers"
 * for architecture, dismiss behaviour, and iframe-nesting limitations.
 */
export declare class PopoverJsApi {
    private readonly logger;
    private readonly serviceChecker;
    private SERVICE?;
    constructor(config: Config);
    init(SERVICE?: AgentxService): void;
    cleanup(): void;
    /**
     * `true` when the calling widget is running inside a host-managed popover
     * iframe. Use this to branch in the single-bundle composition pattern.
     */
    isActive(): boolean;
    /**
     * Open a host-managed popover. Only one popover may be open at a time;
     * opening a new one supersedes the previous one.
     * @returns `{ popoverId }` of the popover that is now open.
     */
    open(options: PopoverOpenOptions): Promise<{
        popoverId: string;
    } | undefined>;
    /** Close the popover owned by this iframe. No-op if none is open. */
    close(): Promise<void>;
    /** Resize the popover iframe. Typically called from the popover content. */
    resize(dimensions: PopoverResizeDimensions): Promise<void>;
    /**
     * Subscribe to popover-open events. Always invoke the returned unsubscribe
     * function in your widget's `disconnectedCallback` to avoid leaks.
     */
    onOpen(callback: (event: PopoverLifecycleEvent) => void): () => void;
    /** Subscribe to popover-close events. Returns an unsubscribe function. */
    onClose(callback: (event: PopoverLifecycleEvent) => void): () => void;
}
export declare const createPopoverJsApi: () => PopoverJsApi;
export {};