gecko-dev/browser/components/asrouter/modules/FeatureCalloutBroker.sys.mjs

/* This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */

const lazy = {};

ChromeUtils.defineESModuleGetters(lazy, {
  FeatureCallout: "resource:///modules/asrouter/FeatureCallout.sys.mjs",
});

/**
 * @typedef {Object} FeatureCalloutOptions
 * @property {Window} win window in which messages will be rendered.
 * @property {{name: String, defaultValue?: String}} [pref] optional pref used
 *   to track progress through a given feature tour. for example:
 *   {
 *     name: "browser.pdfjs.feature-tour",
 *     defaultValue: '{ screen: "FEATURE_CALLOUT_1", complete: false }',
 *   }
 *   or { name: "browser.pdfjs.feature-tour" } (defaultValue is optional)
 * @property {String} [location] string to pass as the page when requesting
 *   messages from ASRouter and sending telemetry.
 * @property {MozBrowser} [browser] <browser> element responsible for the
 *   feature callout. for content pages, this is the browser element that the
 *   callout is being shown in. for chrome, this is the active browser.
 * @property {Function} [cleanup] callback to be invoked when the callout is
 *   removed or the window is unloaded.
 * @property {FeatureCalloutTheme} [theme] optional dynamic color theme.
 */

/** @typedef {import("resource:///modules/asrouter/FeatureCallout.sys.mjs").FeatureCalloutTheme} FeatureCalloutTheme */

/**
 * @typedef {Object} FeatureCalloutItem
 * @property {lazy.FeatureCallout} callout instance of FeatureCallout.
 * @property {Function} [cleanup] cleanup callback.
 * @property {Boolean} showing whether the callout is currently showing.
 */

export class _FeatureCalloutBroker {
  /**
   * Make a new FeatureCallout instance and store it in the callout map. Also
   * add an unload listener to the window to clean up the callout when the
   * window is unloaded.
   * @param {FeatureCalloutOptions} config
   */
  makeFeatureCallout(config) {
    const { win, pref, location, browser, theme } = config;
    // Use an AbortController to clean up the unload listener in case the
    // callout is cleaned up before the window is unloaded.
    const controller = new AbortController();
    const cleanup = () => {
      this.#calloutMap.delete(win);
      controller.abort();
      config.cleanup?.();
    };
    this.#calloutMap.set(win, {
      callout: new lazy.FeatureCallout({
        win,
        pref,
        location,
        context: "chrome",
        browser,
        listener: this.handleFeatureCalloutCallback.bind(this),
        theme,
      }),
      cleanup,
      showing: false,
    });
    win.addEventListener("unload", cleanup, { signal: controller.signal });
  }

  /**
   * Show a feature callout message. For use by ASRouter, to be invoked when a
   * trigger has matched to a feature_callout message.
   * @param {MozBrowser} browser <browser> element associated with the trigger.
   * @param {Object} message feature_callout message from ASRouter.
   *   @see {@link FeatureCalloutMessages.sys.mjs}
   * @returns {Promise<Boolean>} whether the callout was shown.
   */
  async showFeatureCallout(browser, message) {
    // Only show one callout at a time, across all windows.
    if (this.isCalloutShowing) {
      return false;
    }
    const win = browser.ownerGlobal;
    // Avoid showing feature callouts if a dialog or panel is showing.
    if (
      win.gDialogBox?.dialog ||
      [...win.document.querySelectorAll("panel")].some(p => p.state === "open")
    ) {
      return false;
    }
    const currentCallout = this.#calloutMap.get(win);
    // If a custom callout was previously showing, but is no longer showing,
    // tear down the FeatureCallout instance. We avoid tearing them down when
    // they stop showing because they may be shown again, and we want to avoid
    // the overhead of creating a new FeatureCallout instance. But the custom
    // callout instance may be incompatible with the new ASRouter message, so
    // we tear it down and create a new one.
    if (currentCallout && currentCallout.callout.location !== "chrome") {
      currentCallout.cleanup();
    }
    let item = this.#calloutMap.get(win);
    let callout = item?.callout;
    if (item) {
      // If a callout previously showed in this instance, but the new message's
      // tour_pref_name is different, update the old instance's tour properties.
      callout.teardownFeatureTourProgress();
      if (message.content.tour_pref_name) {
        callout.pref = {
          name: message.content.tour_pref_name,
          defaultValue: message.content.tour_pref_default_value,
        };
        callout.setupFeatureTourProgress();
      } else {
        callout.pref = null;
      }
    } else {
      const options = {
        win,
        location: "chrome",
        browser,
        theme: { preset: "chrome" },
      };
      if (message.content.tour_pref_name) {
        options.pref = {
          name: message.content.tour_pref_name,
          defaultValue: message.content.tour_pref_default_value,
        };
      }
      this.makeFeatureCallout(options);
      item = this.#calloutMap.get(win);
      callout = item.callout;
    }
    // Set this to true for now so that we can't be interrupted by another
    // invocation. We'll set it to false below if it ended up not showing.
    item.showing = true;
    item.showing = await callout.showFeatureCallout(message).catch(() => {
      item.cleanup();
      return false;
    });
    return item.showing;
  }

  /**
   * Make a new FeatureCallout instance specific to a special location, tearing
   * down the existing generic FeatureCallout if it exists, and (if no message
   * is passed) requesting a feature callout message to show. Does nothing if a
   * callout is already in progress. This allows the PDF.js feature tour, which
   * simulates content, to be shown in the chrome window without interfering
   * with chrome feature callouts.
   * @param {FeatureCalloutOptions} config
   * @param {Object} message feature_callout message from ASRouter.
   *   @see {@link FeatureCalloutMessages.sys.mjs}
   * @returns {FeatureCalloutItem|null} the callout item, if one was created.
   */
  showCustomFeatureCallout(config, message) {
    if (this.isCalloutShowing) {
      return null;
    }
    const { win, pref, location } = config;
    const currentCallout = this.#calloutMap.get(win);
    if (currentCallout && currentCallout.location !== location) {
      currentCallout.cleanup();
    }
    let item = this.#calloutMap.get(win);
    let callout = item?.callout;
    if (item) {
      callout.teardownFeatureTourProgress();
      callout.pref = pref;
      if (pref) {
        callout.setupFeatureTourProgress();
      }
    } else {
      this.makeFeatureCallout(config);
      item = this.#calloutMap.get(win);
      callout = item.callout;
    }
    item.showing = true;
    // In this case, callers are not necessarily async, so we don't await.
    callout
      .showFeatureCallout(message)
      .then(showing => {
        item.showing = showing;
      })
      .catch(() => {
        item.cleanup();
        item.showing = false;
      });
    /** @type {FeatureCalloutItem} */
    return item;
  }

  handleFeatureCalloutCallback(win, event) {
    switch (event) {
      case "end":
        const item = this.#calloutMap.get(win);
        if (item) {
          item.showing = false;
        }
        break;
    }
  }

  /** @returns {Boolean} whether a callout is currently showing. */
  get isCalloutShowing() {
    return [...this.#calloutMap.values()].some(({ showing }) => showing);
  }

  /** @type {Map<Window, FeatureCalloutItem>} */
  #calloutMap = new Map();
}

export const FeatureCalloutBroker = new _FeatureCalloutBroker();