summaryrefslogtreecommitdiffstats
path: root/browser/modules/FeatureCallout.sys.mjs
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--browser/modules/FeatureCallout.sys.mjs1222
1 files changed, 1222 insertions, 0 deletions
diff --git a/browser/modules/FeatureCallout.sys.mjs b/browser/modules/FeatureCallout.sys.mjs
new file mode 100644
index 0000000000..6c378a878d
--- /dev/null
+++ b/browser/modules/FeatureCallout.sys.mjs
@@ -0,0 +1,1222 @@
+/* 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/. */
+
+import { XPCOMUtils } from "resource://gre/modules/XPCOMUtils.sys.mjs";
+
+const lazy = {};
+
+ChromeUtils.defineESModuleGetters(lazy, {
+ PageEventManager: "resource://activity-stream/lib/PageEventManager.sys.mjs",
+});
+
+XPCOMUtils.defineLazyModuleGetters(lazy, {
+ AboutWelcomeParent: "resource:///actors/AboutWelcomeParent.jsm",
+ ASRouter: "resource://activity-stream/lib/ASRouter.jsm",
+});
+
+const TRANSITION_MS = 500;
+const CONTAINER_ID = "multi-stage-message-root";
+const BUNDLE_SRC =
+ "resource://activity-stream/aboutwelcome/aboutwelcome.bundle.js";
+
+/**
+ * Feature Callout fetches messages relevant to a given source and displays them
+ * in the parent page pointing to the element they describe.
+ */
+export class FeatureCallout {
+ /**
+ * @typedef {Object} FeatureCalloutOptions
+ * @property {Window} win window in which messages will be rendered
+ * @property {String} prefName name of the pref used to track progress through
+ * a given feature tour, e.g. "browser.pdfjs.feature-tour"
+ * @property {String} [page] string to pass as the page when requesting
+ * messages from ASRouter and sending telemetry. for browser chrome, the
+ * string "chrome" is used
+ * @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 {FeatureCalloutTheme} [theme] @see FeatureCallout.themePresets
+ */
+
+ /** @param {FeatureCalloutOptions} options */
+ constructor({ win, prefName, page, browser, theme = {} } = {}) {
+ this.win = win;
+ this.doc = win.document;
+ this.browser = browser || this.win.docShell.chromeEventHandler;
+ this.config = null;
+ this.loadingConfig = false;
+ this.message = null;
+ this.currentScreen = null;
+ this.renderObserver = null;
+ this.savedActiveElement = null;
+ this.ready = false;
+ this._positionListenersRegistered = false;
+ this.AWSetup = false;
+ this.page = page;
+ this._initTheme(theme);
+
+ XPCOMUtils.defineLazyPreferenceGetter(
+ this,
+ "featureTourProgress",
+ prefName,
+ '{"screen":"","complete":true}',
+ this._handlePrefChange.bind(this),
+ val => {
+ try {
+ return JSON.parse(val);
+ } catch (error) {
+ return null;
+ }
+ }
+ );
+
+ XPCOMUtils.defineLazyPreferenceGetter(
+ this,
+ "cfrFeaturesUserPref",
+ "browser.newtabpage.activity-stream.asrouter.userprefs.cfr.features",
+ true,
+ function (pref, previous, latest) {
+ if (latest) {
+ this.showFeatureCallout();
+ } else {
+ this._handlePrefChange();
+ }
+ }.bind(this)
+ );
+ this.featureTourProgress; // Load initial value of progress pref
+
+ // When the window is focused, ensure tour is synced with tours in any other
+ // instances of the parent page. This does not apply when the Callout is
+ // shown in the browser chrome.
+ if (this.page !== "chrome") {
+ this.win.addEventListener("visibilitychange", this);
+ }
+ }
+
+ /**
+ * Get the page event manager and instantiate it if necessary. Only used by
+ * _attachPageEventListeners, since we don't want to do this unnecessary work
+ * if a message with page event listeners hasn't loaded. Other consumers
+ * should use `this._pageEventManager?.property` instead.
+ */
+ get _loadPageEventManager() {
+ if (!this._pageEventManager) {
+ this._pageEventManager = new lazy.PageEventManager(this.doc);
+ }
+ return this._pageEventManager;
+ }
+
+ _addPositionListeners() {
+ if (!this._positionListenersRegistered) {
+ this.win.addEventListener("resize", this);
+ const parentEl = this.doc.querySelector(
+ this.currentScreen?.parent_selector
+ );
+ parentEl?.addEventListener("toggle", this);
+ this._positionListenersRegistered = true;
+ }
+ }
+
+ _removePositionListeners() {
+ if (this._positionListenersRegistered) {
+ this.win.removeEventListener("resize", this);
+ const parentEl = this.doc.querySelector(
+ this.currentScreen?.parent_selector
+ );
+ parentEl?.removeEventListener("toggle", this);
+ this._positionListenersRegistered = false;
+ }
+ }
+
+ async _handlePrefChange() {
+ if (this.doc.visibilityState === "hidden" || !this.featureTourProgress) {
+ return;
+ }
+
+ // If we have more than one screen, it means that we're
+ // displaying a feature tour, and transitions are handled
+ // based on the value of a tour progress pref. Otherwise,
+ // just show the feature callout.
+ if (this.config?.screens.length === 1) {
+ this.showFeatureCallout();
+ return;
+ }
+
+ // If a pref change results from an event in a Spotlight message,
+ // reload the page to clear the Spotlight and initialize the
+ // feature callout with the next message in the tour.
+ if (this.currentScreen == "spotlight") {
+ this.win.location.reload();
+ return;
+ }
+
+ let prefVal = this.featureTourProgress;
+ // End the tour according to the tour progress pref or if the user disabled
+ // contextual feature recommendations.
+ if (prefVal.complete || !this.cfrFeaturesUserPref) {
+ this.endTour();
+ this.currentScreen = null;
+ } else if (prefVal.screen !== this.currentScreen?.id) {
+ this.ready = false;
+ this._container?.classList.add("hidden");
+ this._pageEventManager?.clear();
+ // wait for fade out transition
+ this.win.setTimeout(async () => {
+ await this._loadConfig();
+ this._container?.remove();
+ this._removePositionListeners();
+ this.doc.querySelector(`[src="${BUNDLE_SRC}"]`)?.remove();
+ await this._renderCallout();
+ }, TRANSITION_MS);
+ }
+ }
+
+ handleEvent(event) {
+ switch (event.type) {
+ case "focus": {
+ if (!this._container) {
+ return;
+ }
+ // If focus has fired on the feature callout window itself, or on something
+ // contained in that window, ignore it, as we can't possibly place the focus
+ // on it after the callout is closd.
+ if (
+ event.target === this._container ||
+ (Node.isInstance(event.target) &&
+ this._container.contains(event.target))
+ ) {
+ return;
+ }
+ // Save this so that if the next focus event is re-entering the popup,
+ // then we'll put the focus back here where the user left it once we exit
+ // the feature callout series.
+ this.savedActiveElement = this.doc.activeElement;
+ break;
+ }
+
+ case "keypress": {
+ if (event.key !== "Escape") {
+ return;
+ }
+ if (!this._container) {
+ return;
+ }
+ let focusedElement =
+ this.page === "chrome"
+ ? Services.focus.focusedElement
+ : this.doc.activeElement;
+ // If the window has a focused element, let it handle the ESC key instead.
+ if (
+ !focusedElement ||
+ focusedElement === this.doc.body ||
+ focusedElement === this.browser ||
+ this._container.contains(focusedElement)
+ ) {
+ this.win.AWSendEventTelemetry?.({
+ event: "DISMISS",
+ event_context: {
+ source: `KEY_${event.key}`,
+ page: this.page,
+ },
+ message_id: this.config?.id.toUpperCase(),
+ });
+ this._dismiss();
+ event.preventDefault();
+ }
+ break;
+ }
+
+ case "visibilitychange":
+ this._handlePrefChange();
+ break;
+
+ case "resize":
+ case "toggle":
+ this._positionCallout();
+ break;
+
+ default:
+ }
+ }
+
+ _addCalloutLinkElements() {
+ const addStylesheet = href => {
+ if (this.doc.querySelector(`link[href="${href}"]`)) {
+ return;
+ }
+ const link = this.doc.head.appendChild(this.doc.createElement("link"));
+ link.rel = "stylesheet";
+ link.href = href;
+ };
+ const addLocalization = hrefs => {
+ hrefs.forEach(href => {
+ // eslint-disable-next-line no-undef
+ this.win.MozXULElement.insertFTLIfNeeded(href);
+ });
+ };
+
+ // Update styling to be compatible with about:welcome bundle
+ addStylesheet(
+ "chrome://activity-stream/content/aboutwelcome/aboutwelcome.css"
+ );
+
+ addLocalization([
+ "browser/newtab/onboarding.ftl",
+ "browser/spotlight.ftl",
+ "branding/brand.ftl",
+ "toolkit/branding/brandings.ftl",
+ "browser/newtab/asrouter.ftl",
+ "browser/featureCallout.ftl",
+ ]);
+ }
+
+ _createContainer() {
+ let parent = this.doc.querySelector(this.currentScreen?.parent_selector);
+ // Don't render the callout if the parent element is not present.
+ // This means the message was misconfigured, mistargeted, or the
+ // content of the parent page is not as expected.
+ if (!parent && !this.currentScreen?.content?.callout_position_override) {
+ if (this.message?.template === "feature_callout") {
+ Services.telemetry.recordEvent(
+ "messaging_experiments",
+ "feature_callout",
+ "create_failed",
+ `${this.message.id || "no_message"}-${
+ this.currentScreen?.parent_selector || "no_current_screen"
+ }`
+ );
+ }
+
+ return false;
+ }
+
+ if (!this._container?.parentElement) {
+ this._container = this.doc.createElement("div");
+ this._container.classList.add(
+ "onboardingContainer",
+ "featureCallout",
+ "callout-arrow",
+ "hidden"
+ );
+ this._container.classList.toggle(
+ "hidden-arrow",
+ this.currentScreen?.content?.hide_arrow
+ );
+ this._container.id = CONTAINER_ID;
+ // This value is reported as the "page" in about:welcome telemetry
+ this._container.dataset.page = this.page;
+ this._container.setAttribute(
+ "aria-describedby",
+ `#${CONTAINER_ID} .welcome-text`
+ );
+ this._container.tabIndex = 0;
+ this._applyTheme();
+ this.doc.body.prepend(this._container);
+ }
+ return this._container;
+ }
+
+ /**
+ * Set callout's position relative to parent element
+ */
+ _positionCallout() {
+ const container = this._container;
+ const parentEl = this.doc.querySelector(
+ this.currentScreen?.parent_selector
+ );
+ const doc = this.doc;
+ // All possible arrow positions
+ // If the position contains a dash, the value before the dash
+ // refers to which edge of the feature callout the arrow points
+ // from. The value after the dash describes where along that edge
+ // the arrow sits, with middle as the default.
+ const arrowPositions = [
+ "top",
+ "bottom",
+ "end",
+ "start",
+ "top-end",
+ "top-start",
+ ];
+ const arrowPosition = this.currentScreen?.content?.arrow_position || "top";
+ // Callout should overlap the parent element by 17px (so the box, not
+ // including the arrow, will overlap by 5px)
+ const arrowWidth = 12;
+ let overlap = 17;
+ // If we have no overlap, we send the callout the same number of pixels
+ // in the opposite direction
+ overlap = this.currentScreen?.content?.noCalloutOverlap
+ ? overlap * -1
+ : overlap;
+ overlap -= arrowWidth;
+ // Is the document layout right to left?
+ const RTL = this.doc.dir === "rtl";
+ const customPosition =
+ this.currentScreen?.content.callout_position_override;
+
+ // Early exit if the container doesn't exist,
+ // or if we're missing a parent element and don't have a custom callout position
+ if (!container || (!parentEl && !customPosition)) {
+ return;
+ }
+
+ const getOffset = el => {
+ const rect = el.getBoundingClientRect();
+ return {
+ left: rect.left + this.win.scrollX,
+ right: rect.right + this.win.scrollX,
+ top: rect.top + this.win.scrollY,
+ bottom: rect.bottom + this.win.scrollY,
+ };
+ };
+
+ const clearPosition = () => {
+ Object.keys(positioners).forEach(position => {
+ container.style[position] = "unset";
+ });
+ arrowPositions.forEach(position => {
+ if (container.classList.contains(`arrow-${position}`)) {
+ container.classList.remove(`arrow-${position}`);
+ }
+ if (container.classList.contains(`arrow-inline-${position}`)) {
+ container.classList.remove(`arrow-inline-${position}`);
+ }
+ });
+ };
+
+ const addArrowPositionClassToContainer = finalArrowPosition => {
+ let className;
+ switch (finalArrowPosition) {
+ case "bottom":
+ className = "arrow-bottom";
+ break;
+ case "left":
+ className = "arrow-inline-start";
+ break;
+ case "right":
+ className = "arrow-inline-end";
+ break;
+ case "top-start":
+ className = RTL ? "arrow-top-end" : "arrow-top-start";
+ break;
+ case "top-end":
+ className = RTL ? "arrow-top-start" : "arrow-top-end";
+ break;
+ case "top":
+ default:
+ className = "arrow-top";
+ break;
+ }
+
+ container.classList.add(className);
+ };
+
+ const addValueToPixelValue = (value, pixelValue) => {
+ return `${Number(pixelValue.split("px")[0]) + value}px`;
+ };
+
+ const subtractPixelValueFromValue = (pixelValue, value) => {
+ return `${value - Number(pixelValue.split("px")[0])}px`;
+ };
+
+ const overridePosition = () => {
+ // We override _every_ positioner here, because we want to manually set all
+ // container.style.positions in every positioner's "position" function
+ // regardless of the actual arrow position
+ // Note: We override the position functions with new functions here,
+ // but they don't actually get executed until the respective position functions are called
+ // and this function is not executed unless the message has a custom position property.
+
+ // We're positioning relative to a parent element's bounds,
+ // if that parent element exists.
+
+ for (const position in positioners) {
+ positioners[position].position = () => {
+ if (customPosition.top) {
+ container.style.top = addValueToPixelValue(
+ parentEl.getBoundingClientRect().top,
+ customPosition.top
+ );
+ }
+
+ if (customPosition.left) {
+ const leftPosition = addValueToPixelValue(
+ parentEl.getBoundingClientRect().left,
+ customPosition.left
+ );
+
+ RTL
+ ? (container.style.right = leftPosition)
+ : (container.style.left = leftPosition);
+ }
+
+ if (customPosition.right) {
+ const rightPosition = subtractPixelValueFromValue(
+ customPosition.right,
+ parentEl.getBoundingClientRect().right - container.clientWidth
+ );
+
+ RTL
+ ? (container.style.right = rightPosition)
+ : (container.style.left = rightPosition);
+ }
+
+ if (customPosition.bottom) {
+ container.style.top = subtractPixelValueFromValue(
+ customPosition.bottom,
+ parentEl.getBoundingClientRect().bottom - container.clientHeight
+ );
+ }
+ };
+ }
+ };
+
+ const positioners = {
+ // availableSpace should be the space between the edge of the page in the assumed direction
+ // and the edge of the parent (with the callout being intended to fit between those two edges)
+ // while needed space should be the space necessary to fit the callout container
+ top: {
+ availableSpace() {
+ return (
+ doc.documentElement.clientHeight -
+ getOffset(parentEl).top -
+ parentEl.clientHeight
+ );
+ },
+ neededSpace: container.clientHeight - overlap,
+ position() {
+ // Point to an element above the callout
+ let containerTop =
+ getOffset(parentEl).top + parentEl.clientHeight - overlap;
+ container.style.top = `${Math.max(0, containerTop)}px`;
+ alignHorizontally("center");
+ },
+ },
+ bottom: {
+ availableSpace() {
+ return getOffset(parentEl).top;
+ },
+ neededSpace: container.clientHeight - overlap,
+ position() {
+ // Point to an element below the callout
+ let containerTop =
+ getOffset(parentEl).top - container.clientHeight + overlap;
+ container.style.top = `${Math.max(0, containerTop)}px`;
+ alignHorizontally("center");
+ },
+ },
+ right: {
+ availableSpace() {
+ return getOffset(parentEl).left;
+ },
+ neededSpace: container.clientWidth - overlap,
+ position() {
+ // Point to an element to the right of the callout
+ let containerLeft =
+ getOffset(parentEl).left - container.clientWidth + overlap;
+ container.style.left = `${Math.max(0, containerLeft)}px`;
+ if (container.offsetHeight <= parentEl.offsetHeight) {
+ container.style.top = `${getOffset(parentEl).top}px`;
+ } else {
+ centerVertically();
+ }
+ },
+ },
+ left: {
+ availableSpace() {
+ return doc.documentElement.clientWidth - getOffset(parentEl).right;
+ },
+ neededSpace: container.clientWidth - overlap,
+ position() {
+ // Point to an element to the left of the callout
+ let containerLeft =
+ getOffset(parentEl).left + parentEl.clientWidth - overlap;
+ container.style.left = `${Math.max(0, containerLeft)}px`;
+ if (container.offsetHeight <= parentEl.offsetHeight) {
+ container.style.top = `${getOffset(parentEl).top}px`;
+ } else {
+ centerVertically();
+ }
+ },
+ },
+ "top-start": {
+ availableSpace() {
+ doc.documentElement.clientHeight -
+ getOffset(parentEl).top -
+ parentEl.clientHeight;
+ },
+ neededSpace: container.clientHeight - overlap,
+ position() {
+ // Point to an element above and at the start of the callout
+ let containerTop =
+ getOffset(parentEl).top + parentEl.clientHeight - overlap;
+ container.style.top = `${Math.max(
+ container.clientHeight - overlap,
+ containerTop
+ )}px`;
+ alignHorizontally("start");
+ },
+ },
+ "top-end": {
+ availableSpace() {
+ doc.documentElement.clientHeight -
+ getOffset(parentEl).top -
+ parentEl.clientHeight;
+ },
+ neededSpace: container.clientHeight - overlap,
+ position() {
+ // Point to an element above and at the end of the callout
+ let containerTop =
+ getOffset(parentEl).top + parentEl.clientHeight - overlap;
+ container.style.top = `${Math.max(
+ container.clientHeight - overlap,
+ containerTop
+ )}px`;
+ alignHorizontally("end");
+ },
+ },
+ };
+
+ const calloutFits = position => {
+ // Does callout element fit in this position relative
+ // to the parent element without going off screen?
+
+ // Only consider which edge of the callout the arrow points from,
+ // not the alignment of the arrow along the edge of the callout
+ let edgePosition = position.split("-")[0];
+ return (
+ positioners[edgePosition].availableSpace() >
+ positioners[edgePosition].neededSpace
+ );
+ };
+
+ const choosePosition = () => {
+ let position = arrowPosition;
+ if (!arrowPositions.includes(position)) {
+ // Configured arrow position is not valid
+ return false;
+ }
+ if (["start", "end"].includes(position)) {
+ // position here is referencing the direction that the callout container
+ // is pointing to, and therefore should be the _opposite_ side of the arrow
+ // eg. if arrow is at the "end" in LTR layouts, the container is pointing
+ // at an element to the right of itself, while in RTL layouts it is pointing to the left of itself
+ position = RTL ^ (position === "start") ? "left" : "right";
+ }
+ // If we're overriding the position, we don't need to sort for available space
+ if (customPosition || calloutFits(position)) {
+ return position;
+ }
+ let sortedPositions = Object.keys(positioners)
+ .filter(p => p !== position)
+ .filter(calloutFits)
+ .sort((a, b) => {
+ return (
+ positioners[b].availableSpace() - positioners[b].neededSpace >
+ positioners[a].availableSpace() - positioners[a].neededSpace
+ );
+ });
+ // If the callout doesn't fit in any position, use the configured one.
+ // The callout will be adjusted to overlap the parent element so that
+ // the former doesn't go off screen.
+ return sortedPositions[0] || position;
+ };
+
+ const centerVertically = () => {
+ let topOffset = (container.offsetHeight - parentEl.offsetHeight) / 2;
+ container.style.top = `${getOffset(parentEl).top - topOffset}px`;
+ };
+
+ /**
+ * Horizontally align a top/bottom-positioned callout according to the
+ * passed position.
+ * @param {String} [position = "start"] <"start"|"end"|"center">
+ */
+ const alignHorizontally = position => {
+ switch (position) {
+ case "center": {
+ let sideOffset = (parentEl.clientWidth - container.clientWidth) / 2;
+ let containerSide = RTL
+ ? doc.documentElement.clientWidth -
+ getOffset(parentEl).right +
+ sideOffset
+ : getOffset(parentEl).left + sideOffset;
+ container.style[RTL ? "right" : "left"] = `${Math.max(
+ containerSide,
+ 0
+ )}px`;
+ break;
+ }
+ default: {
+ let containerSide =
+ RTL ^ (position === "end")
+ ? parentEl.getBoundingClientRect().left +
+ parentEl.clientWidth -
+ container.clientWidth
+ : parentEl.getBoundingClientRect().left;
+ container.style.left = `${Math.max(containerSide, 0)}px`;
+ break;
+ }
+ }
+ };
+
+ clearPosition(container);
+
+ if (customPosition) {
+ overridePosition();
+ }
+
+ let finalPosition = choosePosition();
+ if (finalPosition) {
+ positioners[finalPosition].position();
+ addArrowPositionClassToContainer(finalPosition);
+ }
+
+ container.classList.remove("hidden");
+ }
+
+ /** Expose top level functions expected by the aboutwelcome bundle. */
+ _setupWindowFunctions() {
+ if (this.AWSetup) {
+ return;
+ }
+ const AWParent = new lazy.AboutWelcomeParent();
+ this.win.addEventListener("unload", () => {
+ AWParent.didDestroy();
+ });
+ const receive = name => data =>
+ AWParent.onContentMessage(`AWPage:${name}`, data, this.doc);
+ this.win.AWGetFeatureConfig = () => this.config;
+ this.win.AWGetSelectedTheme = receive("GET_SELECTED_THEME");
+ // Do not send telemetry if message config sets metrics as 'block'.
+ if (this.config?.metrics !== "block") {
+ this.win.AWSendEventTelemetry = receive("TELEMETRY_EVENT");
+ }
+ this.win.AWSendToDeviceEmailsSupported = receive(
+ "SEND_TO_DEVICE_EMAILS_SUPPORTED"
+ );
+ this.win.AWSendToParent = (name, data) => receive(name)(data);
+ this.win.AWFinish = () => {
+ this.endTour();
+ };
+ this.win.AWEvaluateScreenTargeting = receive("EVALUATE_SCREEN_TARGETING");
+ this.AWSetup = true;
+ }
+
+ /** Clean up the functions defined above. */
+ _clearWindowFunctions() {
+ const windowFuncs = [
+ "AWGetFeatureConfig",
+ "AWGetSelectedTheme",
+ "AWSendEventTelemetry",
+ "AWSendToDeviceEmailsSupported",
+ "AWSendToParent",
+ "AWFinish",
+ ];
+ windowFuncs.forEach(func => delete this.win[func]);
+ }
+
+ endTour(skipFadeOut = false) {
+ // We don't want focus events that happen during teardown to affect
+ // this.savedActiveElement
+ this.win.removeEventListener("focus", this, {
+ capture: true,
+ passive: true,
+ });
+ this.win.removeEventListener("keypress", this, { capture: true });
+ this._pageEventManager?.clear();
+
+ // We're deleting featureTourProgress here to ensure that the
+ // reference is freed for garbage collection. This prevents errors
+ // caused by lingering instances when instantiating and removing
+ // multiple feature tour instances in succession.
+ delete this.featureTourProgress;
+ this.ready = false;
+ // wait for fade out transition
+ this._container?.classList.add("hidden");
+ this._clearWindowFunctions();
+ this.win.setTimeout(
+ () => {
+ this._container?.remove();
+ this.renderObserver?.disconnect();
+ this._removePositionListeners();
+ this.doc.querySelector(`[src="${BUNDLE_SRC}"]`)?.remove();
+ // Put the focus back to the last place the user focused outside of the
+ // featureCallout windows.
+ if (this.savedActiveElement) {
+ this.savedActiveElement.focus({ focusVisible: true });
+ }
+ },
+ skipFadeOut ? 0 : TRANSITION_MS
+ );
+ }
+
+ _dismiss() {
+ let action = this.currentScreen?.content.dismiss_button?.action;
+ if (action?.type) {
+ this.win.AWSendToParent("SPECIAL_ACTION", action);
+ } else {
+ this.endTour();
+ }
+ }
+
+ async _addScriptsAndRender() {
+ const reactSrc = "resource://activity-stream/vendor/react.js";
+ const domSrc = "resource://activity-stream/vendor/react-dom.js";
+ // Add React script
+ const getReactReady = async () => {
+ return new Promise(resolve => {
+ let reactScript = this.doc.createElement("script");
+ reactScript.src = reactSrc;
+ this.doc.head.appendChild(reactScript);
+ reactScript.addEventListener("load", resolve);
+ });
+ };
+ // Add ReactDom script
+ const getDomReady = async () => {
+ return new Promise(resolve => {
+ let domScript = this.doc.createElement("script");
+ domScript.src = domSrc;
+ this.doc.head.appendChild(domScript);
+ domScript.addEventListener("load", resolve);
+ });
+ };
+ // Load React, then React Dom
+ if (!this.doc.querySelector(`[src="${reactSrc}"]`)) {
+ await getReactReady();
+ }
+ if (!this.doc.querySelector(`[src="${domSrc}"]`)) {
+ await getDomReady();
+ }
+ // Load the bundle to render the content as configured.
+ this.doc.querySelector(`[src="${BUNDLE_SRC}"]`)?.remove();
+ let bundleScript = this.doc.createElement("script");
+ bundleScript.src = BUNDLE_SRC;
+ this.doc.head.appendChild(bundleScript);
+ }
+
+ _observeRender(container) {
+ this.renderObserver?.observe(container, { childList: true });
+ }
+
+ /**
+ * Request a message from ASRouter, targeting the `browser` and `page` values
+ * passed to the constructor. The message content is stored in this.config,
+ * which is returned by AWGetFeatureConfig. The aboutwelcome bundle will use
+ * that function to get the content. It will only be called when the bundle
+ * loads, so the bundle must be reloaded for a new message to be rendered.
+ * @returns {Promise<boolean>} true if a message is loaded, false if not.
+ */
+ async _loadConfig() {
+ if (this.loadingConfig) {
+ return false;
+ }
+ this.loadingConfig = true;
+ await lazy.ASRouter.waitForInitialized;
+ let result = await lazy.ASRouter.sendTriggerMessage({
+ browser: this.browser,
+ // triggerId and triggerContext
+ id: "featureCalloutCheck",
+ context: { source: this.page },
+ });
+ this.message = result.message;
+ this.loadingConfig = false;
+
+ if (result.message.template !== "feature_callout") {
+ // If another message type, like a Spotlight modal, is included
+ // in the tour, save the template name as the current screen.
+ this.currentScreen = result.message.template;
+ return false;
+ }
+
+ this.config = result.message.content;
+
+ let newScreen = this.config?.screens?.[this.config?.startScreen || 0];
+ if (newScreen?.id === this.currentScreen?.id) {
+ return false;
+ }
+
+ // Only add an impression if we actually have a message to impress
+ if (Object.keys(result.message).length) {
+ lazy.ASRouter.addImpression(result.message);
+ }
+
+ this.currentScreen = newScreen;
+ return true;
+ }
+
+ async _renderCallout() {
+ let container = this._createContainer();
+ if (container) {
+ // This results in rendering the Feature Callout
+ await this._addScriptsAndRender();
+ this._observeRender(container);
+ this._addPositionListeners();
+ }
+ }
+
+ /**
+ * For each member of the screen's page_event_listeners array, add a listener.
+ * @param {Array<PageEventListener>} listeners An array of listeners to set up
+ *
+ * @typedef {Object} PageEventListener
+ * @property {PageEventListenerParams} params Event listener parameters
+ * @property {PageEventListenerAction} action Sent when the event fires
+ *
+ * @typedef {Object} PageEventListenerParams See PageEventManager.sys.mjs
+ * @property {String} type Event type string e.g. `click`
+ * @property {String} selectors Target selector, e.g. `tag.class, #id[attr]`
+ * @property {PageEventListenerOptions} [options] addEventListener options
+ *
+ * @typedef {Object} PageEventListenerOptions
+ * @property {Boolean} [capture] Use event capturing phase?
+ * @property {Boolean} [once] Remove listener after first event?
+ * @property {Boolean} [preventDefault] Prevent default action?
+ *
+ * @typedef {Object} PageEventListenerAction Action sent to AboutWelcomeParent
+ * @property {String} [type] Action type, e.g. `OPEN_URL`
+ * @property {Object} [data] Extra data, properties depend on action type
+ * @property {Boolean} [dismiss] Dismiss screen after performing action?
+ */
+ _attachPageEventListeners(listeners) {
+ listeners?.forEach(({ params, action }) =>
+ this._loadPageEventManager[params.options?.once ? "once" : "on"](
+ params,
+ event => {
+ this._handlePageEventAction(action, event);
+ if (params.options?.preventDefault) {
+ event.preventDefault?.();
+ }
+ }
+ )
+ );
+ }
+
+ /**
+ * Perform an action in response to a page event.
+ * @param {PageEventListenerAction} action
+ * @param {Event} event Triggering event
+ */
+ _handlePageEventAction(action, event) {
+ const page = this.page;
+ const message_id = this.config?.id.toUpperCase();
+ const source = this._getUniqueElementIdentifier(event.target);
+ this.win.AWSendEventTelemetry?.({
+ event: "PAGE_EVENT",
+ event_context: {
+ action: action.type ?? (action.dismiss ? "DISMISS" : ""),
+ reason: event.type?.toUpperCase(),
+ source,
+ page,
+ },
+ message_id,
+ });
+ if (action.type) {
+ this.win.AWSendToParent("SPECIAL_ACTION", action);
+ }
+ if (action.dismiss) {
+ this.win.AWSendEventTelemetry?.({
+ event: "DISMISS",
+ event_context: { source: `PAGE_EVENT:${source}`, page },
+ message_id,
+ });
+ this._dismiss();
+ }
+ }
+
+ /**
+ * For a given element, calculate a unique string that identifies it.
+ * @param {Element} target Element to calculate the selector for
+ * @returns {String} Computed event target selector, e.g. `button#next`
+ */
+ _getUniqueElementIdentifier(target) {
+ let source;
+ if (Element.isInstance(target)) {
+ source = target.localName;
+ if (target.className) {
+ source += `.${[...target.classList].join(".")}`;
+ }
+ if (target.id) {
+ source += `#${target.id}`;
+ }
+ if (target.attributes.length) {
+ source += `${[...target.attributes]
+ .filter(attr => ["is", "role", "open"].includes(attr.name))
+ .map(attr => `[${attr.name}="${attr.value}"]`)
+ .join("")}`;
+ }
+ if (this.doc.querySelectorAll(source).length > 1) {
+ let uniqueAncestor = target.closest(`[id]:not(:scope, :root, body)`);
+ if (uniqueAncestor) {
+ source = `${this._getUniqueElementIdentifier(
+ uniqueAncestor
+ )} > ${source}`;
+ }
+ }
+ }
+ return source;
+ }
+
+ async showFeatureCallout() {
+ let updated = await this._loadConfig();
+
+ if (!updated || !this.config?.screens?.length) {
+ return;
+ }
+
+ this.renderObserver = new this.win.MutationObserver(() => {
+ // Check if the Feature Callout screen has loaded for the first time
+ if (!this.ready && this._container.querySelector(".screen")) {
+ // Once the screen element is added to the DOM, wait for the
+ // animation frame after next to ensure that _positionCallout
+ // has access to the rendered screen with the correct height
+ this.win.requestAnimationFrame(() => {
+ this.win.requestAnimationFrame(() => {
+ this.ready = true;
+ this._attachPageEventListeners(
+ this.currentScreen?.content?.page_event_listeners
+ );
+ this.win.addEventListener("keypress", this, { capture: true });
+ this._positionCallout();
+ let button = this._container.querySelector(".primary");
+ button.focus();
+ this.win.addEventListener("focus", this, {
+ capture: true, // get the event before retargeting
+ passive: true,
+ });
+ });
+ });
+ }
+ });
+
+ this._pageEventManager?.clear();
+ this.ready = false;
+ this._container?.remove();
+
+ // If user has disabled CFR, don't show any callouts. But make sure we load
+ // the necessary stylesheets first, since re-enabling CFR should allow
+ // callouts to be shown without needing to reload. In the future this could
+ // allow adding a CTA to disable recommendations with a label like "Don't show
+ // these again" (or potentially a toggle to re-enable them).
+ if (!this.cfrFeaturesUserPref) {
+ this.currentScreen = null;
+ return;
+ }
+
+ this._addCalloutLinkElements();
+ this._setupWindowFunctions();
+ await this._renderCallout();
+ }
+
+ /**
+ * @typedef {Object} FeatureCalloutTheme An object with a set of custom color
+ * schemes and/or a preset key. If both are provided, the preset will be
+ * applied first, then the custom themes will override the preset values.
+ * @property {String} [preset] Key of {@link FeatureCallout.themePresets}
+ * @property {ColorScheme} [light] Custom light scheme
+ * @property {ColorScheme} [dark] Custom dark scheme
+ * @property {ColorScheme} [hcm] Custom high contrast scheme
+ * @property {ColorScheme} [all] Custom scheme that will be applied in all
+ * cases, but overridden by the other schemes if they are present. This is
+ * useful if the values are already controlled by the browser theme.
+ * @property {Boolean} [simulateContent] Set to true if the feature callout
+ * exists in the browser chrome but is meant to be displayed over the
+ * content area to appear as if it is part of the page. This will cause the
+ * styles to use a media query targeting the content instead of the chrome,
+ * so that if the browser theme doesn't match the content color scheme, the
+ * callout will correctly follow the content scheme. This is currently used
+ * for the feature callouts displayed over the PDF.js viewer.
+ */
+
+ /**
+ * @typedef {Object} ColorScheme An object with key-value pairs, with keys
+ * from {@link FeatureCallout.themePropNames}, mapped to CSS color values
+ */
+
+ /**
+ * Combine the preset and custom themes into a single object and store it.
+ * @param {FeatureCalloutTheme} theme
+ */
+ _initTheme(theme) {
+ /** @type {FeatureCalloutTheme} */
+ this.theme = Object.assign(
+ {},
+ FeatureCallout.themePresets[theme.preset],
+ theme
+ );
+ }
+
+ /**
+ * Apply all the theme colors to the feature callout's root element as CSS
+ * custom properties in inline styles. These custom properties are consumed by
+ * _feature-callout-theme.scss, which is bundled with the other styles that
+ * are loaded by {@link FeatureCallout.prototype._addCalloutLinkElements}.
+ */
+ _applyTheme() {
+ if (this._container) {
+ // This tells the stylesheets to use -moz-content-prefers-color-scheme
+ // instead of prefers-color-scheme, in order to follow the content color
+ // scheme instead of the chrome color scheme, in case of a mismatch when
+ // the feature callout exists in the chrome but is meant to look like it's
+ // part of the content of a page in a browser tab (like PDF.js).
+ this._container.classList.toggle(
+ "simulateContent",
+ this.page === "chrome" && this.theme.simulateContent
+ );
+ for (const type of ["light", "dark", "hcm"]) {
+ const scheme = this.theme[type];
+ for (const name of FeatureCallout.themePropNames) {
+ this._setThemeVariable(
+ `--fc-${name}-${type}`,
+ scheme?.[name] || this.theme.all?.[name]
+ );
+ }
+ }
+ }
+ }
+
+ /**
+ * Set or remove a CSS custom property on the feature callout container
+ * @param {String} name Name of the CSS custom property
+ * @param {String|void} [value] Value of the property, or omit to remove it
+ */
+ _setThemeVariable(name, value) {
+ if (value) {
+ this._container.style.setProperty(name, value);
+ } else {
+ this._container.style.removeProperty(name);
+ }
+ }
+
+ /** A list of all the theme properties that can be set */
+ static themePropNames = [
+ "background",
+ "color",
+ "border",
+ "accent-color",
+ "button-background",
+ "button-color",
+ "button-border",
+ "button-background-hover",
+ "button-color-hover",
+ "button-border-hover",
+ "button-background-active",
+ "button-color-active",
+ "button-border-active",
+ ];
+
+ /** @type {Object<String, FeatureCalloutTheme>} */
+ static themePresets = {
+ // For themed system pages like New Tab and Firefox View. Themed content
+ // colors inherit from the user's theme through contentTheme.js.
+ "themed-content": {
+ all: {
+ background: "var(--newtab-background-color-secondary)",
+ color: "var(--newtab-text-primary-color, var(--in-content-page-color))",
+ border:
+ "color-mix(in srgb, var(--newtab-background-color-secondary) 80%, #000)",
+ "accent-color": "var(--in-content-primary-button-background)",
+ "button-background": "color-mix(in srgb, transparent 93%, #000)",
+ "button-color":
+ "var(--newtab-text-primary-color, var(--in-content-page-color))",
+ "button-border": "transparent",
+ "button-background-hover": "color-mix(in srgb, transparent 88%, #000)",
+ "button-color-hover":
+ "var(--newtab-text-primary-color, var(--in-content-page-color))",
+ "button-border-hover": "transparent",
+ "button-background-active": "color-mix(in srgb, transparent 80%, #000)",
+ "button-color-active":
+ "var(--newtab-text-primary-color, var(--in-content-page-color))",
+ "button-border-active": "transparent",
+ },
+ dark: {
+ border:
+ "color-mix(in srgb, var(--newtab-background-color-secondary) 80%, #FFF)",
+ "button-background": "color-mix(in srgb, transparent 80%, #000)",
+ "button-background-hover": "color-mix(in srgb, transparent 65%, #000)",
+ "button-background-active": "color-mix(in srgb, transparent 55%, #000)",
+ },
+ hcm: {
+ background: "-moz-dialog",
+ color: "-moz-dialogtext",
+ border: "-moz-dialogtext",
+ "accent-color": "LinkText",
+ "button-background": "ButtonFace",
+ "button-color": "ButtonText",
+ "button-border": "ButtonText",
+ "button-background-hover": "ButtonText",
+ "button-color-hover": "ButtonFace",
+ "button-border-hover": "ButtonText",
+ "button-background-active": "ButtonText",
+ "button-color-active": "ButtonFace",
+ "button-border-active": "ButtonText",
+ },
+ },
+ // PDF.js colors are from toolkit/components/pdfjs/content/web/viewer.css
+ pdfjs: {
+ all: {
+ background: "#FFF",
+ color: "rgb(12, 12, 13)",
+ border: "#CFCFD8",
+ "accent-color": "#0A84FF",
+ "button-background": "rgb(215, 215, 219)",
+ "button-color": "rgb(12, 12, 13)",
+ "button-border": "transparent",
+ "button-background-hover": "rgb(221, 222, 223)",
+ "button-color-hover": "rgb(12, 12, 13)",
+ "button-border-hover": "transparent",
+ "button-background-active": "rgb(221, 222, 223)",
+ "button-color-active": "rgb(12, 12, 13)",
+ "button-border-active": "transparent",
+ },
+ dark: {
+ background: "#1C1B22",
+ color: "#F9F9FA",
+ border: "#3A3944",
+ "button-background": "rgb(74, 74, 79)",
+ "button-color": "#F9F9FA",
+ "button-background-hover": "rgb(102, 102, 103)",
+ "button-color-hover": "#F9F9FA",
+ "button-background-active": "rgb(102, 102, 103)",
+ "button-color-active": "#F9F9FA",
+ },
+ hcm: {
+ background: "-moz-dialog",
+ color: "-moz-dialogtext",
+ border: "CanvasText",
+ "accent-color": "Highlight",
+ "button-background": "ButtonFace",
+ "button-color": "ButtonText",
+ "button-border": "ButtonText",
+ "button-background-hover": "Highlight",
+ "button-color-hover": "CanvasText",
+ "button-border-hover": "Highlight",
+ "button-background-active": "Highlight",
+ "button-color-active": "CanvasText",
+ "button-border-active": "Highlight",
+ },
+ },
+ // These colors are intended to inherit the user's theme properties from the
+ // main chrome window, for callouts to be anchored to chrome elements.
+ // Specific schemes aren't necessary since the theme and frontend
+ // stylesheets handle these variables' values.
+ chrome: {
+ all: {
+ background: "var(--arrowpanel-background)",
+ color: "var(--arrowpanel-color)",
+ border: "var(--arrowpanel-border-color)",
+ "accent-color": "var(--focus-outline-color)",
+ "button-background": "var(--button-bgcolor)",
+ "button-color": "var(--arrowpanel-color)",
+ "button-border": "transparent",
+ "button-background-hover": "var(--button-hover-bgcolor)",
+ "button-color-hover": "var(--arrowpanel-color)",
+ "button-border-hover": "transparent",
+ "button-background-active": "var(--button-active-bgcolor)",
+ "button-color-active": "var(--arrowpanel-color)",
+ "button-border-active": "transparent",
+ },
+ },
+ };
+}