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 {
        commitCommandPaletteSelection(webViewId: string): Promise<void>;
        dismissCommandPalette(webViewId: string): Promise<void>;
        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>;
        updateCommandPalette(
            webViewId: string,
            update: { filterText?: string; moveSelection?: number },
        ): Promise<void>;
        updatePopover(overlayId: string, content: PopoverContent): Promise<void>;
    }
    Index

    Methods

    commitCommandPaletteSelection dismissCommandPalette dismissPopover onPopoverDismissed showCommandPalette showContextMenu showPopover updateCommandPalette updatePopover

    Methods

    • Commits the currently highlighted item of the active command palette for the given WebView, resolving its showCommandPalette promise with that item's id (mirrors how a click on a command palette item resolves the promise). If the highlighted item is disabled, moves forward to the next enabled item in the filtered list; if none are enabled, no-ops. No-op if no command palette is active for that WebView.

      Keyed by webViewId for the same reason as updateCommandPalette.

      Parameters

      • webViewId: string

        The ID of the WebView whose command palette selection should be committed

      Returns Promise<void>

    • Dismisses the active command palette for the given WebView, resolving its showCommandPalette promise with undefined. Works for both active and passive palettes. No-op if no command palette is active for that WebView.

      Keyed by webViewId for the same reason as updateCommandPalette.

      Parameters

      • webViewId: string

        The ID of the WebView whose command palette should be dismissed

      Returns Promise<void>

    • 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.

      LocalizeKey item text (label/description/badge) is resolved to localized strings when the palette is shown, so all filtering — the palette's own search box and text forwarded via updateCommandPalette — matches against the text the user actually sees.

      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

    • Updates the filter text and/or moves the highlighted selection of the active command palette for the given WebView. No-op if no command palette is active for that WebView.

      Unlike the popover family above (keyed by the overlay ID returned from showPopover), the command palette mutators are keyed by webViewId instead. The service enforces one command palette per WebView at a time (see this interface's class docs), so the requesting WebView's own ID is a sufficient handle — passive-mode callers drive the palette without ever seeing an overlay ID.

      Parameters

      • webViewId: string

        The ID of the WebView whose command palette should be updated

      • update: { filterText?: string; moveSelection?: number }

        filterText and/or moveSelection (clamped to the filtered list's bounds). filterText drives passive palettes' list directly and, for ACTIVE palettes, the (controlled) search input — callers forward keystrokes this way when the cross-frame focus handoff loses and the user's typing lands in their WebView instead of the palette.

      Returns Promise<void>

    • 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