feat(client): share the building indicator and track builds by source (#2369)

The badge state lives in a window singleton (same pattern as the
overlay), so a second bundled copy of the module drives the same badge
instead of stacking a duplicate, and fields missing from another
version's state are filled in place.

show() and hide() take an optional source: each concurrent build keeps
the badge alive until every source finished, so in a MultiCompiler one
bundle's `built` no longer hides the badge while a sibling is still
compiling — and with two clients sharing the badge, one client's hide()
cannot drop the other's indication. hide() without a source still
removes the badge unconditionally. Progress payloads carry no name, so
the client attributes them to the most recent `building` event.

Author: bjohansebas

README.md

@@ -459,6 +459,18 @@ show("Rebuilding… 42%", 42); // progress ring
 hide();
 ```
 
+The badge is a per-page singleton shared by every bundled copy of the module.
+Concurrent builds can report through a `source` — the badge stays until every
+source finished:
+
+```js
+show("Rebuilding app…", undefined, "app");
+show("Rebuilding admin…", undefined, "admin");
+hide("app"); // still shown — "admin" is building
+hide("admin"); // removed
+hide(); // without a source: removed unconditionally
+```
+
 ## HMR notes and troubleshooting
 
 ### Browser connection limits (many tabs)

client-src/index.js

@@ -418,6 +418,10 @@ let customHandler;
 /** @type {((obj: HMRPayload) => void) | undefined} */
 let subscribeAllHandler;
 
+// Name of the build that most recently reported `building` — progress
+// payloads carry no name, so they are attributed to it.
+let lastBuildingName = "";
+
 /**
  * @param {HMRPayload} obj payload
  */
@@ -430,23 +434,31 @@ function processMessage(obj) {
         }`,
       );
       if (options.progress && typeof document !== "undefined") {
-        indicator.show(obj.file ? `Rebuilding… (${obj.file})` : undefined);
+        lastBuildingName = obj.name || "";
+        indicator.show(
+          obj.file ? `Rebuilding… (${obj.file})` : undefined,
+          undefined,
+          lastBuildingName,
+        );
       }
       break;
     }
     case "progress": {
+      // Progress payloads carry no name — attribute them to the build that
+      // most recently reported `building`.
       if (options.progress && typeof document !== "undefined") {
         indicator.show(
           `Rebuilding… ${obj.percent}%${obj.message ? ` (${obj.message})` : ""}`,
           obj.percent,
+          lastBuildingName,
         );
       }
       break;
     }
     case "built":
     case "sync": {
       if (options.progress && typeof document !== "undefined") {
-        indicator.hide();
+        indicator.hide(obj.name || "");
       }
       if (obj.action === "built") {
         log.info(

client-src/indicator.js

@@ -9,20 +9,60 @@ const SVG_NS = "http://www.w3.org/2000/svg";
 // Circumference of the progress ring (r = 6).
 const RING_LENGTH = 2 * Math.PI * 6;
 
-/** @type {HTMLElement | null} */
-let host = null;
-/** @type {HTMLElement | null} */
-let label = null;
-/** @type {HTMLElement | null} */
-let dot = null;
-/** @type {SVGSVGElement | null} */
-let ring = null;
-/** @type {SVGCircleElement | null} */
-let ringValue = null;
-
 // eslint-disable-next-line jsdoc/reject-any-type
 /** @typedef {any} EXPECTED_ANY */
 
+/**
+ * @typedef {object} IndicatorState
+ * @property {HTMLElement | null} host badge host element
+ * @property {HTMLElement | null} label label inside the badge
+ * @property {HTMLElement | null} dot pulsing dot (indeterminate mode)
+ * @property {SVGSVGElement | null} ring progress ring (determinate mode)
+ * @property {SVGCircleElement | null} ringValue ring value circle
+ * @property {Record<string, true>} building sources with a build in progress — the badge hides only when every source finished
+ */
+
+/** @returns {IndicatorState} fresh indicator state */
+function createIndicatorState() {
+  return {
+    host: null,
+    label: null,
+    dot: null,
+    ring: null,
+    ringValue: null,
+    building: {},
+  };
+}
+
+// Shared through `window` so every bundled copy of this module drives one
+// single badge instead of stacking duplicates (same pattern as the overlay).
+const INDICATOR_STATE_KEY = "__webpack_dev_middleware_hot_indicator_state__";
+
+/** @type {IndicatorState} */
+const state = (() => {
+  if (typeof window === "undefined") {
+    return createIndicatorState();
+  }
+
+  const holder = /** @type {EXPECTED_ANY} */ (window);
+
+  if (!holder[INDICATOR_STATE_KEY]) {
+    holder[INDICATOR_STATE_KEY] = createIndicatorState();
+  } else {
+    // Fill fields another package version may not have created, in place.
+    const defaults = createIndicatorState();
+
+    for (const key of Object.keys(defaults)) {
+      if (!(key in holder[INDICATOR_STATE_KEY])) {
+        holder[INDICATOR_STATE_KEY][key] =
+          defaults[/** @type {keyof IndicatorState} */ (key)];
+      }
+    }
+  }
+
+  return holder[INDICATOR_STATE_KEY];
+})();
+
 /**
  * @param {EXPECTED_ANY} element element
  * @param {Record<string, string | number>} style style map
@@ -37,25 +77,25 @@ function applyStyle(element, style) {
  * Create (or reuse) the indicator host element.
  */
 function ensureIndicator() {
-  if (host && host.parentNode) {
+  if (state.host && state.host.parentNode) {
     return;
   }
 
   if (!document.body) {
     return;
   }
 
-  host = document.createElement("div");
-  host.id = INDICATOR_ID;
-  applyStyle(host, {
+  state.host = document.createElement("div");
+  state.host.id = INDICATOR_ID;
+  applyStyle(state.host, {
     position: "fixed",
     right: "16px",
     bottom: "16px",
     zIndex: 9999,
     pointerEvents: "none",
   });
 
-  const root = host.attachShadow({ mode: "open" });
+  const root = state.host.attachShadow({ mode: "open" });
 
   const badge = document.createElement("div");
   applyStyle(badge, {
@@ -72,26 +112,26 @@ function ensureIndicator() {
   });
 
   // Indeterminate mode: a pulsing dot.
-  dot = document.createElement("span");
-  applyStyle(dot, {
+  state.dot = document.createElement("span");
+  applyStyle(state.dot, {
     width: "8px",
     height: "8px",
     borderRadius: "50%",
     background: theme.accent,
   });
 
   // Pulse through the Web Animations API — no <style> element involved.
-  if (typeof dot.animate === "function") {
-    dot.animate([{ opacity: 1 }, { opacity: 0.2 }, { opacity: 1 }], {
+  if (typeof state.dot.animate === "function") {
+    state.dot.animate([{ opacity: 1 }, { opacity: 0.2 }, { opacity: 1 }], {
       duration: 1000,
       iterations: Number.POSITIVE_INFINITY,
     });
   }
 
   // Determinate mode: a progress ring drawn with SVG presentation attributes.
-  ring = document.createElementNS(SVG_NS, "svg");
-  ring.setAttribute("viewBox", "0 0 16 16");
-  applyStyle(ring, { width: "14px", height: "14px", display: "none" });
+  state.ring = document.createElementNS(SVG_NS, "svg");
+  state.ring.setAttribute("viewBox", "0 0 16 16");
+  applyStyle(state.ring, { width: "14px", height: "14px", display: "none" });
 
   const track = document.createElementNS(SVG_NS, "circle");
   track.setAttribute("cx", "8");
@@ -101,72 +141,91 @@ function ensureIndicator() {
   track.setAttribute("stroke", "rgba(255,255,255,0.25)");
   track.setAttribute("stroke-width", "2.5");
 
-  ringValue = document.createElementNS(SVG_NS, "circle");
-  ringValue.setAttribute("cx", "8");
-  ringValue.setAttribute("cy", "8");
-  ringValue.setAttribute("r", "6");
-  ringValue.setAttribute("fill", "none");
-  ringValue.setAttribute("stroke", theme.accent);
-  ringValue.setAttribute("stroke-width", "2.5");
-  ringValue.setAttribute("stroke-linecap", "round");
-  ringValue.setAttribute("stroke-dasharray", String(RING_LENGTH));
-  ringValue.setAttribute("stroke-dashoffset", String(RING_LENGTH));
+  state.ringValue = document.createElementNS(SVG_NS, "circle");
+  state.ringValue.setAttribute("cx", "8");
+  state.ringValue.setAttribute("cy", "8");
+  state.ringValue.setAttribute("r", "6");
+  state.ringValue.setAttribute("fill", "none");
+  state.ringValue.setAttribute("stroke", theme.accent);
+  state.ringValue.setAttribute("stroke-width", "2.5");
+  state.ringValue.setAttribute("stroke-linecap", "round");
+  state.ringValue.setAttribute("stroke-dasharray", String(RING_LENGTH));
+  state.ringValue.setAttribute("stroke-dashoffset", String(RING_LENGTH));
   // Start the ring at 12 o'clock.
-  ringValue.setAttribute("transform", "rotate(-90 8 8)");
+  state.ringValue.setAttribute("transform", "rotate(-90 8 8)");
 
-  ring.append(track, ringValue);
+  state.ring.append(track, state.ringValue);
 
-  label = document.createElement("span");
-  badge.append(dot, ring, label);
+  state.label = document.createElement("span");
+  badge.append(state.dot, state.ring, state.label);
   root.append(badge);
-  document.body.append(host);
+  document.body.append(state.host);
 }
 
 /**
  * Show the indicator (idempotent). With a percent the badge renders a
  * progress ring; without one it renders a pulsing dot.
  * @param {string=} text label text
  * @param {number=} percent compilation progress (0-100)
+ * @param {string=} source who is building (e.g. a compilation name, or a
+ * client sharing the badge) — the badge stays until every source finished
  */
-export function show(text, percent) {
+export function show(text, percent, source = "") {
+  state.building[source] = true;
   ensureIndicator();
 
-  if (!label) {
+  if (!state.label) {
     return;
   }
 
-  label.textContent = text || "Rebuilding…";
+  state.label.textContent = text || "Rebuilding…";
 
   const determinate = typeof percent === "number";
 
-  /** @type {HTMLElement} */ (dot).style.display = determinate
+  /** @type {HTMLElement} */ (state.dot).style.display = determinate
     ? "none"
     : "inline-block";
-  /** @type {SVGSVGElement} */ (ring).style.display = determinate
+  /** @type {SVGSVGElement} */ (state.ring).style.display = determinate
     ? "block"
     : "none";
 
   if (determinate) {
     const clamped = Math.min(100, Math.max(0, percent));
 
-    /** @type {SVGCircleElement} */ (ringValue).setAttribute(
+    /** @type {SVGCircleElement} */ (state.ringValue).setAttribute(
       "stroke-dashoffset",
       String(RING_LENGTH * (1 - clamped / 100)),
     );
   }
 }
 
 /**
- * Remove the indicator from the page.
+ * Mark one source's build as finished, or remove the indicator entirely.
+ * @param {string=} source when given, only that source is dropped and the
+ * badge stays while any other source is still building; without it the badge
+ * is removed unconditionally
  */
-export function hide() {
-  if (host && host.parentNode) {
-    host.remove();
+export function hide(source) {
+  if (source !== undefined) {
+    if (!Object.prototype.hasOwnProperty.call(state.building, source)) {
+      return;
+    }
+
+    delete state.building[source];
+
+    if (Object.keys(state.building).length > 0) {
+      return;
+    }
+  }
+
+  if (state.host && state.host.parentNode) {
+    state.host.remove();
   }
 
-  host = null;
-  label = null;
-  dot = null;
-  ring = null;
-  ringValue = null;
+  state.host = null;
+  state.label = null;
+  state.dot = null;
+  state.ring = null;
+  state.ringValue = null;
+  state.building = {};
 }

test/client.test.js

@@ -93,6 +93,7 @@ describe("client", () => {
     delete globalThis.EventSource;
     delete globalThis.__wdmEventSourceWrapper;
     delete globalThis.__webpack_dev_middleware_hot_reporter__;
+    delete globalThis.__webpack_dev_middleware_hot_indicator_state__;
     jest.useRealTimers();
   });
 
@@ -892,6 +893,39 @@ describe("client", () => {
 
       expect(document.getElementById(INDICATOR_ID)).toBeNull();
     });
+
+    it("keeps the badge until every compilation finished", () => {
+      loadClient();
+      const es = EventSourceStub.lastInstance();
+
+      es.onmessage(makeMessage({ action: "building", name: "app" }));
+      es.onmessage(makeMessage({ action: "building", name: "admin" }));
+
+      es.onmessage(
+        makeMessage({
+          action: "built",
+          name: "app",
+          time: 1,
+          hash: "h1",
+          errors: [],
+          warnings: [],
+        }),
+      );
+      // "admin" is still building — its `built` has not arrived yet.
+      expect(document.getElementById(INDICATOR_ID)).not.toBeNull();
+
+      es.onmessage(
+        makeMessage({
+          action: "built",
+          name: "admin",
+          time: 1,
+          hash: "h2",
+          errors: [],
+          warnings: [],
+        }),
+      );
+      expect(document.getElementById(INDICATOR_ID)).toBeNull();
+    });
   });
 
   describe("connection lifecycle", () => {