// Copyright 2022 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

// Use the `chrome.sidePanel` API to host content in the browser's side panel
// alongside the main content of a webpage.
namespace sidePanel {
  dictionary SidePanel {
    // Developer specified path for side panel display.
    DOMString default_path;
  };

  dictionary ManifestKeys {
    SidePanel? side_panel;
  };

  // Defines the possible alignment for the side panel in the browser UI.
  enum Side {
    left,
    right
  };

  // Represents the layout of the side panel, indicating which side it is shown.
  dictionary PanelLayout {
    Side side;
  };

  // The options used when setting a side panel. Omitted properties are
  // unchanged.
  dictionary PanelOptions {
    // If specified, the side panel options will only apply to the tab with
    // this id. If omitted, these options set the default behavior (used for any
    // tab that doesn't have specific settings). Note: if the same path is set
    // for this tabId and the default tabId, then the panel for this tabId will
    // be a different instance than the panel for the default tabId.
    long? tabId;
    // The path to the side panel HTML file to use. This must be a local
    // resource within the extension package.
    DOMString? path;
    // Whether the side panel should be enabled. This is optional. The default
    // value is true.
    boolean? enabled;
  };

  // A dictionary containing the extension's options for how its side panel
  // behaves.
  dictionary PanelBehavior {
    // Whether clicking the extension's icon will toggle showing the extension's
    // entry in the side panel. Defaults to false.
    boolean? openPanelOnActionClick;
  };

  dictionary GetPanelOptions {
    // If specified, the side panel options for the given tab will be returned.
    // Otherwise, returns the default side panel options (used for any tab that
    // doesn't have specific settings).
    long? tabId;
  };

  // Options for opening the side panel.
  // At least one of `tabId` or `windowId` must be specified.
  dictionary OpenOptions {
    // The window in which to open the side panel. This is only applicable if
    // the extension has a global (non-tab-specific) side panel or
    // <code>tabId</code> is also specified. This will override any
    // currently-active global side panel the user has open in the given
    // window. At least one of this or <code>tabId</code> must be provided.
    long? windowId;

    // The tab in which to open the side panel. If the corresponding tab has
    // a tab-specific side panel, the panel will only be open for that tab.
    // If there is not a tab-specific panel, the global panel will be open in
    // the specified tab and any other tabs without a currently-open tab-
    // specific panel. This will override any currently-active side panel
    // (global or tab-specific) in the corresponding tab. At least one of this
    // or <code>windowId</code> must be provided.
    long? tabId;
  };

  // Options for closing the side panel.
  // At least one of `tabId` or `windowId` must be specified.
  dictionary CloseOptions {
    // The window in which to close the side panel. If a global side panel is
    // open in the specified window, it will be closed for all tabs in that
    // window where no tab-specific panel is active. At least one of this or
    // <code>tabId</code> must be provided.
    long? windowId;

    // The tab in which to close the side panel. If a tab-specific side panel
    // is open in the specified tab, it will be closed for that tab. If only the
    // global side panel is open, the promise returned by the call to
    // <code>close()</code> will reject with an error. This behavior was changed
    // in Chrome 145, with prior versions falling back to closing the global
    // panel. At least one of this or <code>windowId</code> must be provided.
    long? tabId;
  };

  // Information about the opened side panel. It is fired when the extension's
  // side panel is opened.
  dictionary PanelOpenedInfo {
    // The ID of the window where the side panel is opened. This is available
    // for both global and tab-specific panels.
    long windowId;

    // The optional ID of the tab where the side panel is opened. This is
    // provided only when the panel is tab-specific.
    long? tabId;

    // The path of the local resource within the extension package whose content
    // is displayed in the panel.
    DOMString path;
  };

  // Information about the closed side panel. It is fired when the extension's
  // side panel is closed.
  dictionary PanelClosedInfo {
    // The ID of the window where the side panel was closed. This is available
    // for both global and tab-specific panels.
    long windowId;

    // The optional ID of the tab where the side panel was closed. This is
    // provided only when the panel is tab-specific.
    long? tabId;

    // The path of the local resource within the extension package whose content
    // is displayed in the panel.
    DOMString path;
  };

  callback VoidCallback = void();
  callback PanelOptionsCallback = void(PanelOptions options);
  callback PanelBehaviorCallback = void(PanelBehavior behavior);
  callback PanelLayoutCallback = void(PanelLayout layout);

  interface Functions {
    // Configures the side panel.
    // |options|: The configuration options to apply to the panel.
    // |callback|: Returns a Promise which resolves when the options have been
    // set.
    static void setOptions(
        PanelOptions options,
        optional VoidCallback callback);

    // Returns the active panel configuration.
    // |options|: Specifies the context to return the configuration for.
    // |callback|: Returns a Promise which resolves with the active panel
    // configuration.
    static void getOptions(
        GetPanelOptions options,
        PanelOptionsCallback callback);

    // Configures the extension's side panel behavior. This is an upsert
    // operation.
    // |behavior|: The new behavior to be set.
    // |callback|: Returns a Promise which resolves when the new behavior has
    // been set.
    static void setPanelBehavior(
        PanelBehavior behavior,
        optional VoidCallback callback);

    // Returns the extension's current side panel behavior.
    // |callback|: Returns a Promise which resolves with the extension's side
    // panel behavior.
    static void getPanelBehavior(
        PanelBehaviorCallback callback);

    // Opens the side panel for the extension.
    // This may only be called in response to a user action.
    // |options|: Specifies the context in which to open the side panel.
    // |callback|: Returns a Promise which resolves when the side panel has been
    // opened.
    static void open(
        OpenOptions options,
        VoidCallback callback);

    // Returns the side panel's current layout.
    // |callback|: Returns a Promise which resolves with a $(ref:PanelLayout).
    static void getLayout(PanelLayoutCallback callback);

    // Closes the extension's side panel.
    // This is a no-op if the panel is already closed.
    // |options|: Specifies the context in which to close the side panel.
    // |callback|: Returns a Promise which resolves when the side panel has been
    // closed.
    static void close(
        CloseOptions options,
        VoidCallback callback);
  };

  interface Events {
    // Fired when the extension's side panel is opened.
    static void onOpened(PanelOpenedInfo info);

    // Fired when the extension's side panel is closed.
    static void onClosed(PanelClosedInfo info);
  };
};