@jsenv/core 41.4.10 → 41.4.12

package/src/plugins/dependency_status/client/dependency_status.js

@@ -3,11 +3,22 @@
  *
  * A missing dependency is not handled here: it makes the import fail, so the
  * error overlay already says it, with more precision (which import, where).
+ *
+ * The overlay does not only describe the problem, it shows the dev server
+ * watching for the fix: the paths being looked at are named and kept alive on
+ * screen, so waiting for "npm install" feels like waiting for something that is
+ * actually going to happen.
  */
 
 let removeOverlay = () => {};
+let watchInfoFromServer = {};
+// packages listed as outdated at some point, and the path watched for each;
+// what leaves this map has been installed while the overlay was open, which is
+// worth showing as such
+const outdatedPathMap = new Map();
 
-export const initDependencyStatus = ({ problems }) => {
+export const initDependencyStatus = ({ problems, watchInfo }) => {
+  watchInfoFromServer = watchInfo || {};
   render(problems);
   // without the server events channel the page only knows the state it was
   // served with, which is still better than nothing
@@ -24,9 +35,19 @@ const render = (problems) => {
   const outdatedList = problems.filter(({ state }) => state === "outdated");
   removeOverlay();
   removeOverlay = () => {};
+  const installedList = [];
+  for (const [packageName, watchedPath] of outdatedPathMap) {
+    if (!outdatedList.some((problem) => problem.packageName === packageName)) {
+      installedList.push({ packageName, watchedPath });
+    }
+  }
   if (outdatedList.length === 0) {
+    outdatedPathMap.clear();
     return;
   }
+  for (const { packageName, watchedPath } of outdatedList) {
+    outdatedPathMap.set(packageName, watchedPath);
+  }
   const supervisor = window.__supervisor__;
   if (!supervisor || !supervisor.reportWarning) {
     console.warn(summarize(outdatedList));
@@ -41,8 +62,8 @@ const render = (problems) => {
     details: [
       "The page is running with what is installed in node_modules, which is not what package.json asks for. It may work, but it is not the code the project expects.",
       "Run npm install to fix it. If an install is already running, there is nothing to do but wait.",
-      "This page reloads on its own as soon as node_modules matches package.json.",
     ],
+    node: createWatchNode(outdatedList, installedList),
   });
 };
 
@@ -57,3 +78,213 @@ const summarize = (outdatedList) => {
     .map(({ packageName }) => packageName)
     .join(", ")}`;
 };
+
+const createWatchNode = (outdatedList, installedList) => {
+  const { packageJsonPath = "package.json", pollInterval } =
+    watchInfoFromServer;
+  const node = document.createElement("div");
+  node.className = "dependency_watch";
+  const rows = [];
+  rows.push(
+    createRow({
+      state: "watching",
+      path: packageJsonPath,
+      // a file watcher, not a poll: an edit here is what puts a dependency out
+      // of date in the first place
+      note: "on every change",
+      pollInterval,
+    }),
+  );
+  for (const { packageName, declaredVersion, watchedPath } of outdatedList) {
+    rows.push(
+      createRow({
+        state: "watching",
+        path: watchedPath || `node_modules/${packageName}/package.json`,
+        note: pollInterval
+          ? `waiting for ${declaredVersion}, read every ${pollInterval}ms`
+          : `waiting for ${declaredVersion}`,
+        pollInterval,
+      }),
+    );
+  }
+  for (const { packageName, watchedPath } of installedList) {
+    rows.push(
+      createRow({
+        state: "done",
+        path: watchedPath || `node_modules/${packageName}/package.json`,
+        note: "installed",
+      }),
+    );
+  }
+  node.innerHTML = `
+<style>
+  ${watchCSS}
+</style>
+<div class="dependency_watch_head">
+  <span class="dependency_watch_live">
+    <span class="dependency_watch_live_dot"></span>watching
+  </span>
+  <span class="dependency_watch_head_text">
+    the files that will tell the install is over
+  </span>
+</div>
+<div class="dependency_watch_rows">
+  ${rows.join("\n  ")}
+</div>
+<div class="dependency_watch_effect" data-copy-line>
+  As soon as node_modules matches package.json, this page reloads by itself.
+</div>`;
+  return node;
+};
+
+const createRow = ({ state, path, note, pollInterval }) => {
+  const sweepStyle = pollInterval
+    ? ` style="animation-duration: ${pollInterval}ms"`
+    : "";
+  return `<div class="dependency_watch_row" data-state="${state}">
+    <span class="dependency_watch_row_icon"></span>
+    <code class="dependency_watch_row_path">${escapeHtml(path)}</code>
+    <span class="dependency_watch_row_note">${escapeHtml(note)}</span>
+    ${
+      state === "watching"
+        ? `<span class="dependency_watch_row_sweep"${sweepStyle}></span>`
+        : ""
+    }
+  </div>`;
+};
+
+const escapeHtml = (string) => {
+  return String(string)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#039;");
+};
+
+const watchCSS = /* css */ `
+  .dependency_watch_head {
+    display: flex;
+    margin-bottom: 8px;
+    align-items: center;
+    gap: 8px;
+  }
+  .dependency_watch_live {
+    display: flex;
+    padding: 2px 8px;
+    align-items: center;
+    gap: 6px;
+    color: #ffab40;
+    font-size: 12px;
+    text-transform: uppercase;
+    letter-spacing: 0.08em;
+    border: 1px solid currentColor;
+    border-radius: 999px;
+  }
+  .dependency_watch_live_dot {
+    width: 7px;
+    height: 7px;
+    background: currentColor;
+    border-radius: 50%;
+    animation: dependency_watch_pulse 1.4s ease-in-out infinite;
+  }
+  @keyframes dependency_watch_pulse {
+    0%,
+    100% {
+      opacity: 0.25;
+      transform: scale(0.8);
+    }
+    50% {
+      opacity: 1;
+      transform: scale(1.15);
+    }
+  }
+  .dependency_watch_head_text {
+    font-size: 13px;
+  }
+
+  .dependency_watch_rows {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+  }
+  .dependency_watch_row {
+    position: relative;
+    display: flex;
+    padding: 6px 10px;
+    align-items: center;
+    gap: 8px;
+    font-size: 13px;
+    background: rgba(255, 255, 255, 0.04);
+    border: 1px solid #333;
+    border-radius: 4px;
+    overflow: hidden;
+  }
+  .dependency_watch_row_icon {
+    width: 8px;
+    height: 8px;
+    flex: none;
+    border: 1px solid #ffab40;
+    border-radius: 50%;
+  }
+  .dependency_watch_row[data-state="done"] .dependency_watch_row_icon {
+    background: #7fd67f;
+    border-color: #7fd67f;
+  }
+  .dependency_watch_row_path {
+    color: #eee;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    overflow: hidden;
+  }
+  .dependency_watch_row_note {
+    margin-left: auto;
+    padding-left: 8px;
+    font-size: 12px;
+    white-space: nowrap;
+    opacity: 0.8;
+  }
+  .dependency_watch_row[data-state="done"] .dependency_watch_row_note {
+    color: #7fd67f;
+    opacity: 1;
+  }
+  /* the sweep is the watching made visible: one pass per read */
+  .dependency_watch_row_sweep {
+    position: absolute;
+    top: 0;
+    left: 0;
+    width: 35%;
+    height: 100%;
+    background: linear-gradient(
+      90deg,
+      transparent,
+      rgba(255, 171, 64, 0.16),
+      transparent
+    );
+    animation: dependency_watch_sweep 2s linear infinite;
+    pointer-events: none;
+  }
+  @keyframes dependency_watch_sweep {
+    from {
+      transform: translateX(-100%);
+    }
+    to {
+      transform: translateX(340%);
+    }
+  }
+
+  .dependency_watch_effect {
+    margin-top: 8px;
+    color: #ffab40;
+    font-size: 13px;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .dependency_watch_live_dot {
+      animation: none;
+    }
+    .dependency_watch_row_sweep {
+      display: none;
+    }
+  }
+`;

package/src/plugins/dependency_status/jsenv_plugin_dependency_status.js

@@ -15,6 +15,7 @@ const clientFileUrl = import.meta.resolve("./client/dependency_status.js");
 export const jsenvPluginDependencyStatus = ({
   dependencyProblemEventEmitter,
   getDependencyProblems,
+  getDependencyWatchInfo = () => ({}),
 }) => {
   return {
     name: "jsenv:dependency_status",
@@ -51,7 +52,10 @@ export const jsenvPluginDependencyStatus = ({
           src: clientReference.generatedSpecifier,
           initCall: {
             callee: "initDependencyStatus",
-            params: { problems: getDependencyProblems() },
+            params: {
+              problems: getDependencyProblems(),
+              watchInfo: getDependencyWatchInfo(),
+            },
           },
           pluginName: "jsenv:dependency_status",
         });

package/src/plugins/ribbon/client/ribbon.js

@@ -1,49 +1,117 @@
-export const injectRibbon = ({ text }) => {
+/*
+ * A ribbon marking a page as non-production: "DEV" while developing, whatever
+ * the app wants otherwise ("preview", a version number, a branch name).
+ *
+ * Two shapes, picked by "position":
+ * - a corner ("top-right", "top-left", "bottom-right", "bottom-left") draws the
+ *   diagonal band clipped by a 100x100 square in that corner
+ * - an edge ("top", "bottom") draws a full width horizontal band
+ *
+ * The container never captures pointer events; only the visible band does, and
+ * only when "href" turns it into a link. A corner ribbon therefore costs the app
+ * nothing: the rest of the 100x100 square keeps letting clicks through to the
+ * interface underneath, which usually lives exactly there.
+ */
+
+const CORNER_POSITIONS = {
+  "top-right": {
+    placement: `top: 0; right: 0;`,
+    transform: `translate(26px, -26px) rotate(45deg)`,
+  },
+  "top-left": {
+    placement: `top: 0; left: 0;`,
+    transform: `translate(-26px, -26px) rotate(-45deg)`,
+  },
+  "bottom-right": {
+    placement: `bottom: 0; right: 0;`,
+    transform: `translate(26px, 26px) rotate(-45deg)`,
+  },
+  "bottom-left": {
+    placement: `bottom: 0; left: 0;`,
+    transform: `translate(-26px, 26px) rotate(45deg)`,
+  },
+};
+const EDGE_POSITIONS = {
+  top: `top: 0; left: 0; right: 0;`,
+  bottom: `bottom: 0; left: 0; right: 0;`,
+};
+const DARK_TEXT_COLOR = "rgb(55, 7, 7)";
+const LIGHT_TEXT_COLOR = "rgb(255, 255, 255)";
+
+export const injectRibbon = ({
+  text = "DEV",
+  color = "orange",
+  textColor,
+  href,
+  target = "_blank",
+  position = "top-right",
+}) => {
+  if (!CORNER_POSITIONS[position] && !EDGE_POSITIONS[position]) {
+    console.warn(
+      `unknown ribbon position "${position}", falling back to "top-right"`,
+    );
+    position = "top-right";
+  }
+  if (textColor === undefined) {
+    textColor = pickTextColorFor(color);
+  }
+  const corner = CORNER_POSITIONS[position];
   const css = /* css */ `
     #jsenv_ribbon_container {
       position: fixed;
-      top: 0;
-      right: 0;
       z-index: 1001;
-      width: 100px;
-      height: 100px;
-      opacity: 0.5;
       pointer-events: none;
       overflow: hidden;
-    }
-    #jsenv_ribbon {
-      position: absolute;
-      top: -10px;
-      right: -10px;
-      width: 100%;
-      height: 100%;
+      ${corner
+        ? `width: 100px; height: 100px; ${corner.placement}`
+        : EDGE_POSITIONS[position]}
     }
     #jsenv_ribbon_text {
-      position: absolute;
-      top: 20px;
-      left: 0px;
       display: block;
-      width: 125px;
-      color: rgb(55, 7, 7);
+      color: ${textColor};
       font-weight: 700;
       font-size: 16px;
       font-family: "Lato", sans-serif;
       text-align: center;
+      text-decoration: none;
       text-shadow: 0 1px 1px rgba(0, 0, 0, 0.2);
-      line-height: 36px;
-      background-color: orange;
+      background-color: ${color};
       box-shadow: 0 5px 10px rgba(0, 0, 0, 0.1);
-      transform: rotate(45deg);
+      opacity: 0.8;
+      transition: opacity 150ms ease;
       user-select: none;
+      ${corner
+        ? `
+      position: absolute;
+      top: 50%;
+      left: 50%;
+      width: 150px;
+      margin-top: -18px;
+      margin-left: -75px;
+      line-height: 36px;
+      transform: ${corner.transform};`
+        : `
+      position: relative;
+      width: 100%;
+      line-height: 28px;`}
+    }
+    /* A ribbon without href never receives pointer events, so it stays at 0.8:
+       covering enough to be read in one go, transparent enough to guess what is
+       underneath */
+    #jsenv_ribbon_text:hover,
+    #jsenv_ribbon_text:focus-visible {
+      opacity: 1;
     }
   `;
+  const tagName = href ? "a" : "div";
+  const linkAttributes = href
+    ? ` href="${escapeHtmlAttributeValue(href)}" target="${escapeHtmlAttributeValue(target)}" rel="noopener noreferrer" style="pointer-events: auto;"`
+    : "";
   const html = /* html */ `<div id="jsenv_ribbon_container">
       <style>
         ${css}
       </style>
-      <div id="jsenv_ribbon">
-        <div id="jsenv_ribbon_text">${text}</div>
-      </div>
+      <${tagName} id="jsenv_ribbon_text"${linkAttributes}>${text}</${tagName}>
     </div>`;
   class JsenvRibbonHtmlElement extends HTMLElement {
     constructor({ hidden }) {
@@ -72,6 +140,34 @@ export const injectRibbon = ({ text }) => {
   );
 };
 
+// The browser is the only one knowing what "orange" or "oklch(...)" resolves to,
+// so we let it resolve the color before deciding between dark and light text
+const pickTextColorFor = (color) => {
+  const probeElement = document.createElement("div");
+  probeElement.style.color = color;
+  document.body.appendChild(probeElement);
+  const colorComputed = getComputedStyle(probeElement).color;
+  probeElement.remove();
+  const rgbMatch = /rgba?\(\s*([\d.]+)[,\s]+([\d.]+)[,\s]+([\d.]+)/.exec(
+    colorComputed,
+  );
+  if (!rgbMatch) {
+    return DARK_TEXT_COLOR;
+  }
+  const r = parseFloat(rgbMatch[1]);
+  const g = parseFloat(rgbMatch[2]);
+  const b = parseFloat(rgbMatch[3]);
+  const brightness = (0.299 * r + 0.587 * g + 0.114 * b) / 255;
+  if (brightness > 0.55) {
+    return DARK_TEXT_COLOR;
+  }
+  return LIGHT_TEXT_COLOR;
+};
+
+const escapeHtmlAttributeValue = (value) => {
+  return String(value).replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+};
+
 const appendIntoRespectingLineBreaksAndIndentation = (
   node,
   parentNode,

package/src/plugins/ribbon/jsenv_plugin_ribbon.js

@@ -5,6 +5,12 @@ import { asUrlWithoutSearch } from "@jsenv/urls";
 export const jsenvPluginRibbon = ({
   rootDirectoryUrl,
   htmlInclude = "/**/*.html",
+  text,
+  color,
+  textColor,
+  href,
+  target,
+  position,
 }) => {
   const ribbonClientFileUrl = import.meta.resolve("./client/ribbon.js");
   const associations = URL_META.resolveAssociations(
@@ -17,7 +23,7 @@ export const jsenvPluginRibbon = ({
   );
   return {
     name: "jsenv:ribbon",
-    appliesDuring: "dev",
+    appliesDuring: "*",
     transformUrlContent: {
       html: (urlInfo) => {
         const jsenvToolbarHtmlClientFileUrl = urlInfo.context.getPluginMeta(
@@ -52,9 +58,19 @@ export const jsenvPluginRibbon = ({
           src: ribbonClientFileReference.generatedSpecifier,
           initCall: {
             callee: "injectRibbon",
-            params: {
-              text: urlInfo.context.dev ? "DEV" : "BUILD",
-            },
+            params: withoutUndefinedValues({
+              text:
+                text === undefined
+                  ? urlInfo.context.dev
+                    ? "DEV"
+                    : "BUILD"
+                  : text,
+              color,
+              textColor,
+              href,
+              target,
+              position,
+            }),
           },
           pluginName: "jsenv:ribbon",
         });
@@ -63,3 +79,13 @@ export const jsenvPluginRibbon = ({
     },
   };
 };
+
+const withoutUndefinedValues = (object) => {
+  const objectWithoutUndefinedValues = {};
+  for (const key of Object.keys(object)) {
+    if (object[key] !== undefined) {
+      objectWithoutUndefinedValues[key] = object[key];
+    }
+  }
+  return objectWithoutUndefinedValues;
+};

package/src/plugins/ribbon/ribbon_html_injection.js

@@ -0,0 +1,38 @@
+/*
+ * Inject the ribbon into an html string, inlining the client code.
+ *
+ * Used when serving files that must not be modified on the filesystem (the build
+ * directory served by startBuildServer): the ribbon exists only in what the
+ * server sends, never in the artifact that gets deployed.
+ */
+
+import { injectJsenvScript, parseHtml, stringifyHtmlAst } from "@jsenv/ast";
+import { readFileSync } from "node:fs";
+
+const ribbonClientFileUrl = import.meta.resolve("./client/ribbon.js");
+let ribbonClientFileContent;
+
+export const injectRibbonIntoHtml = (
+  html,
+  { text = "BUILD", color, textColor, href, target, position } = {},
+) => {
+  if (ribbonClientFileContent === undefined) {
+    ribbonClientFileContent = String(
+      readFileSync(new URL(ribbonClientFileUrl)),
+    );
+  }
+  const htmlAst = parseHtml({ html, url: "file:///ribbon.html" });
+  const params = { text, color, textColor, href, target, position };
+  for (const key of Object.keys(params)) {
+    if (params[key] === undefined) {
+      delete params[key];
+    }
+  }
+  injectJsenvScript(htmlAst, {
+    type: "module",
+    content: `${ribbonClientFileContent}
+injectRibbon(${JSON.stringify(params)});`,
+    pluginName: "jsenv:ribbon",
+  });
+  return stringifyHtmlAst(htmlAst);
+};