papi-dts
    Preparing search index...

    Interface IOverlayService

    Service for showing overlays (context menus, popovers, command palettes) that render outside iframe boundaries in the renderer's top-level document. Renderer-only service.

    Extensions in sandboxed WebView iframes cannot render UI above other content or outside their iframe bounds. This service accepts overlay requests from WebViews, translates their iframe-relative coordinates to document-level coordinates, and renders the overlay in the renderer's React tree. Each method returns a promise that resolves when the user interacts with the overlay or it is dismissed.

    Only one overlay of each type (context menu, popover, command palette) can be active per WebView at a time. Requesting a new overlay of the same type from the same WebView replaces the previous one and rejects its promise with a PlatformError with code ABORTED.

    interface IOverlayService {
        dismissPopover(overlayId: string): Promise<void>;
        onPopoverDismissed(overlayId: string): Promise<undefined | string>;
        showCommandPalette(
            request: CommandPaletteRequest,
            webViewId: string,
        ): Promise<undefined | string>;
        showContextMenu(
            webViewType: string,
            webViewId: string,
            options?: { position?: { x: number; y: number } },
        ): Promise<undefined | string>;
        showPopover(request: PopoverRequest, webViewId: string): Promise<string>;
        updatePopover(overlayId: string, content: PopoverContent): Promise<void>;
    }
    Index

    Methods

    dismissPopover onPopoverDismissed showCommandPalette showContextMenu showPopover updatePopover

    Methods

    • Programmatically dismisses a popover, resolving its onPopoverDismissed promise with undefined. No-op if the popover has already been dismissed or does not exist.

      Parameters

      • overlayId: string

        The overlay ID returned by showPopover

      Returns Promise<void>

    • Returns a promise that resolves when the specified popover is dismissed. Resolves with the PopoverAction id if the user clicked an action button, or undefined if the popover was dismissed by clicking outside, calling dismissPopover, or via auto-dismiss timer. Resolves immediately with undefined if the overlay ID is not found (already dismissed).

      Parameters

      • overlayId: string

        The overlay ID returned by showPopover

      Returns Promise<undefined | string>

      The action ID that triggered dismissal, or undefined

      PlatformError with code ABORTED if the popover was replaced by a new one from the same WebView

    • Shows a command palette with searchable/filterable items. Returns a promise that resolves with the selected item's id, or undefined if dismissed.

      Parameters

      • request: CommandPaletteRequest

        The items, optional anchor position, and display options

      • webViewId: string

        The ID of the WebView requesting the command palette

      Returns Promise<undefined | string>

      The selected item's ID, or undefined if dismissed

      PlatformError with code INVALID_ARGUMENT if the request is invalid

      PlatformError with code ABORTED if replaced by another command palette from the same WebView

    • Shows a context menu from menu.json contributions registered for the given webViewType. Fetches menu data, renders the menu, and auto-executes the selected command. Returns the command string that was executed, or undefined if dismissed.

      Parameters

      • webViewType: string

        The webViewType to look up in the menu data service

      • webViewId: string

        The ID of the WebView requesting the context menu. Pass globalThis.webViewId from within a WebView iframe.

      • Optionaloptions: { position?: { x: number; y: number } }

        Optional context including the position for the menu

      Returns Promise<undefined | string>

      The command string that was executed, or undefined if dismissed

      PlatformError with code ABORTED if replaced by another context menu from the same WebView

    • Shows a popover anchored to the specified position. Unlike context menus and modals, popovers return immediately with an overlay ID rather than waiting for dismissal. Use onPopoverDismissed to await the result, updatePopover to change content, and dismissPopover to close it programmatically.

      Parameters

      • request: PopoverRequest

        The popover anchor, content, and behavioral options

      • webViewId: string

        The ID of the WebView requesting the popover. Pass globalThis.webViewId from within a WebView iframe.

      Returns Promise<string>

      The overlay ID string, usable with other popover methods

      PlatformError with code RESOURCE_EXHAUSTED if a duplicate request arrives within the debounce cooldown

      PlatformError with code INVALID_ARGUMENT if the request is invalid

      PlatformError with code ABORTED if replaced by another popover from the same WebView

    • Replaces the content of an existing popover without closing and reopening it. Useful for updating status messages or showing loading progress.

      Parameters

      Returns Promise<void>

      If no popover with the given ID exists

    Settings

    Member Visibility

    On This Page

    Methods