EthicalAd: switch between light/dark mode on Furo (#624)

Initial implementation to try out ad in dark mode on ethicalads:

- It shows the ad in the defined style at the beginning
- It listens to changes in the theme mode and switch ad theme as well
- It only works on furo for now
- The structure will be the same for other themes, we just need to
implement minor details on them

### Sidebar ad

Note that I had to use `style=image` instead of
`style=readthedocs-sidebar` because the latter doesn't support dark
mode. We should probably implement this in the ad client, and switch it
back here.

[Peek 2025-07-22
11-39.webm](https://github.com/user-attachments/assets/7c4d272c-d13e-44b7-a954-c142b148691e)

### Text ad at the bottom of the page

[Peek 2025-07-22
11-40.webm](https://github.com/user-attachments/assets/e01d8718-85c9-44ff-9bf9-641f5e501766)


### Fixed footer text ad

Note this is not adding in this PR because it needs this chunk of code
to work: [`d7d3c9e`
(#618)](d7d3c9e#diff-10e47ee23788d0e8d3d4e13cee726fd04c8fe035922a74ac1c7d432db1dfb9faR102).
If we want to have it working, I can bring that code in here.

[Peek 2025-07-22
11-46.webm](https://github.com/user-attachments/assets/9630eab2-3da1-469c-aa1a-a80c6e0d85ce)


Related readthedocs/meta#192

---------

Co-authored-by: Eric Holscher <[email protected]>
Co-authored-by: Eric Holscher <[email protected]>

Author: humitos

src/constants.js

@@ -20,3 +20,8 @@ export const SPHINX_IMMATERIAL = "immaterial";
 
 // API URLs
 export const EMBED_API_ENDPOINT = "/_/api/v3/embed/";
+
+// Theme modes
+export const THEME_LIGHT_MODE = "light-mode";
+export const THEME_DARK_MODE = "dark-mode";
+export const THEME_UNKNOWN_MODE = "unknown-mode";

src/ethicalads.js

@@ -3,6 +3,7 @@ import { AddonBase } from "./utils";
 import { default as objectPath } from "object-path";
 import styleSheet from "./ethicalads.css";
 import { IS_TESTING, docTool } from "./utils.js";
+import { THEME_DARK_MODE } from "./constants.js";
 
 // https://docs.readthedocs.io/en/stable/advertising/ad-customization.html#controlling-the-placement-of-an-ad
 const EXPLICIT_PLACEMENT_SELECTORS = [
@@ -103,8 +104,12 @@ export class EthicalAdsAddon extends AddonBase {
         element = document.querySelector(selector);
 
         if (this.elementAboveTheFold(element)) {
-          placement.classList.add("ethical-alabaster");
-          placement.setAttribute("data-ea-type", "readthedocs-sidebar");
+          // NOTE: I'm using `image` instead of `readthedocs-sidebar` because
+          // the later doesn't support dark mode.
+          //
+          // placement.classList.add("ethical-alabaster");
+          // placement.setAttribute("data-ea-type", "readthedocs-sidebar");
+          placement.setAttribute("data-ea-type", "image");
           knownPlacementFound = true;
         }
       } else if (docTool.isSphinxBookThemeLikeTheme()) {
@@ -149,8 +154,7 @@ export class EthicalAdsAddon extends AddonBase {
           placement.classList.add("ethical-alabaster");
           placement.classList.add("ethical-docusaurus");
 
-          placement.setAttribute("data-ea-type", "readthedocs-sidebar");
-          placement.setAttribute("data-ea-style", "image");
+          placement.setAttribute("data-ea-type", "image");
           knownPlacementFound = true;
         }
       } else if (docTool.isDocsify()) {
@@ -255,6 +259,11 @@ export class EthicalAdsAddon extends AddonBase {
         );
       }
 
+      // Add dark class to the ad when we detect dark mode from the beginning
+      if (docTool.documentationThemeMode === THEME_DARK_MODE) {
+        placement.classList.add("dark");
+      }
+
       if (placementStyle == "fixedfooter") {
         // Use a ``MutationObserver`` to listen to style changes in the fixed footer ad.
         // Grab the height of it and use to add some ``padding-bottom`` to the required elements.

src/utils.js

@@ -17,6 +17,9 @@ import {
   VITEPRESS,
   ANTORA,
   DOCSIFY,
+  THEME_LIGHT_MODE,
+  THEME_DARK_MODE,
+  THEME_UNKNOWN_MODE,
 } from "./constants";
 import { EVENT_READTHEDOCS_URL_CHANGED } from "./events";
 
@@ -412,7 +415,47 @@ export class DocumentationTool {
   constructor() {
     this.documentationTool = this.getDocumentationTool();
     this.documentationTheme = this.getDocumentationTheme();
+    this.documentationThemeMode = this.getDocumentationThemeMode();
+
     console.debug(`Documentation tool detected: ${this.documentationTool}`);
+    console.debug(`Documentation theme detected: ${this.documentationTheme}`);
+    console.debug(
+      `Documentation theme mode detected: ${this.documentationThemeMode}`,
+    );
+
+    this.connectEvents();
+  }
+
+  /**
+   * Connect all required events.
+   *
+   * There may be events that are doctool agnostic and some others that are
+   * specific for paticular doctools or themes.
+   */
+  connectEvents() {
+    // Use a ``MutationObserver`` to listen to attribute changes in the `document.html` and `document.body` elements.
+    // Different frameworks update different attributes:
+    //   - Furo Sphinx Theme: `document.body.data-theme`
+    //   - Docusaurus: `document.html.data-theme`
+    //   - VitePress: `document.html.class` ("dark" or nothing)
+    //   - PyData Sphinx Theme: `document.html.data-theme` and `document.html.data-mode`
+    //   - Shibuya Sphinx Theme: `document.html.data-color`
+    //   - mystmd: `document.html.class`
+
+    const config = { attributes: true, childList: false, subtree: false };
+    const callback = (mutationList, observer) => {
+      console.debug("Observed element mutated.", mutationList, observer);
+      for (const mutation of mutationList) {
+        if (mutation.type === "attributes") {
+          this.updateAdThemeMode();
+        }
+      }
+    };
+    const observer = new MutationObserver(callback);
+    // <html> element
+    observer.observe(document.documentElement, config);
+    // <body> element
+    observer.observe(document.body, config);
   }
 
   /**
@@ -566,6 +609,67 @@ export class DocumentationTool {
     return null;
   }
 
+  getDocumentationThemeMode() {
+    let theme;
+    const themeSelector =
+      "html[data-theme], html[data-mode], html[data-color], body[data-theme]";
+    const themes = {
+      auto: THEME_UNKNOWN_MODE,
+      light: THEME_LIGHT_MODE,
+      dark: THEME_DARK_MODE,
+    };
+
+    const prefersDarkMode = window.matchMedia(
+      "(prefers-color-scheme: dark)",
+    ).matches;
+
+    for (const attribute of ["theme", "mode", "color"]) {
+      theme = document.querySelector(themeSelector)?.dataset[attribute];
+      if (theme) break;
+    }
+    if (theme === undefined) {
+      theme = document.querySelector("html.dark") ? "dark" : undefined;
+    }
+    if (theme === undefined) {
+      theme = document.querySelector("html.light") ? "light" : undefined;
+    }
+
+    if (Object.keys(themes).includes(theme)) {
+      if (theme !== "auto") {
+        return themes[theme];
+      } else if (prefersDarkMode) {
+        return THEME_DARK_MODE;
+      } else {
+        return THEME_LIGHT_MODE;
+      }
+    }
+
+    return THEME_UNKNOWN_MODE;
+  }
+
+  updateAdThemeMode() {
+    let placement;
+    // NOTE: can't be imported from `ethicalads.js` because cycle importing
+    const EXPLICIT_PLACEMENT_SELECTORS = [
+      "#ethical-ad-placement",
+      "[data-ea-publisher]",
+    ];
+
+    for (const explicitSelector of EXPLICIT_PLACEMENT_SELECTORS) {
+      placement = document.querySelector(explicitSelector);
+      if (placement) break;
+    }
+
+    if (!placement) return;
+
+    this.documentationThemeMode = this.getDocumentationThemeMode();
+    if (this.documentationThemeMode === THEME_DARK_MODE) {
+      placement.classList.add("dark");
+    } else {
+      placement.classList.remove("dark");
+    }
+  }
+
   isSinglePageApplication() {
     const isSPA = DocumentationTool.SINGLE_PAGE_APPLICATIONS.includes(
       this.documentationTool,