@jsenv/core 41.4.10 → 41.4.12

package/dist/build/build.js

@@ -196,12 +196,21 @@ const createStatus = (
     declaredVersion,
     declaredBy,
     installedVersion: null,
+    // the file telling this dependency apart; it is what an install rewrites and
+    // what the dev server looks at to know the dependency became the declared one
+    watchedPath: null,
     state: "missing",
   };
   const installedDirectoryUrl = findInstalledDirectoryUrl(
     declaringDirectoryUrl,
     packageName,
   );
+  status.watchedPath = watchedPathFromDirectoryUrl(
+    packageDirectory,
+    // not installed yet: name the place where it is expected to appear
+    installedDirectoryUrl ||
+      `${declaringDirectoryUrl}node_modules/${packageName}/`,
+  );
   if (!installedDirectoryUrl) {
     return status;
   }
@@ -220,6 +229,14 @@ const createStatus = (
   return status;
 };
 
+const watchedPathFromDirectoryUrl = (packageDirectory, directoryUrl) => {
+  const packageJsonUrl = `${directoryUrl}package.json`;
+  if (!packageDirectory.url) {
+    return packageJsonUrl;
+  }
+  return urlToRelativeUrl(packageJsonUrl, packageDirectory.url);
+};
+
 const findInstalledDirectoryUrl = (declaringDirectoryUrl, packageName) => {
   let directoryUrl = declaringDirectoryUrl;
   while (directoryUrl) {
@@ -9298,6 +9315,7 @@ const clientFileUrl = import.meta.resolve("../js/dependency_status.js");
 const jsenvPluginDependencyStatus = ({
   dependencyProblemEventEmitter,
   getDependencyProblems,
+  getDependencyWatchInfo = () => ({}),
 }) => {
   return {
     name: "jsenv:dependency_status",
@@ -9334,7 +9352,10 @@ const jsenvPluginDependencyStatus = ({
           src: clientReference.generatedSpecifier,
           initCall: {
             callee: "initDependencyStatus",
-            params: { problems: getDependencyProblems() },
+            params: {
+              problems: getDependencyProblems(),
+              watchInfo: getDependencyWatchInfo(),
+            },
           },
           pluginName: "jsenv:dependency_status",
         });
@@ -9408,6 +9429,12 @@ const jsenvPluginCustomElementsRedefine = () => {
 const jsenvPluginRibbon = ({
   rootDirectoryUrl,
   htmlInclude = "/**/*.html",
+  text,
+  color,
+  textColor,
+  href,
+  target,
+  position,
 }) => {
   const ribbonClientFileUrl = import.meta.resolve("../client/ribbon/ribbon.js");
   const associations = URL_META.resolveAssociations(
@@ -9420,7 +9447,7 @@ const jsenvPluginRibbon = ({
   );
   return {
     name: "jsenv:ribbon",
-    appliesDuring: "dev",
+    appliesDuring: "*",
     transformUrlContent: {
       html: (urlInfo) => {
         const jsenvToolbarHtmlClientFileUrl = urlInfo.context.getPluginMeta(
@@ -9455,9 +9482,19 @@ 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",
         });
@@ -9467,6 +9504,16 @@ const jsenvPluginRibbon = ({
   };
 };
 
+const withoutUndefinedValues = (object) => {
+  const objectWithoutUndefinedValues = {};
+  for (const key of Object.keys(object)) {
+    if (object[key] !== undefined) {
+      objectWithoutUndefinedValues[key] = object[key];
+    }
+  }
+  return objectWithoutUndefinedValues;
+};
+
 /**
  * HTML page server by jsenv dev server will listen for drop events
  * and redirect the browser to the dropped file location.
@@ -12153,6 +12200,18 @@ const jsenvPluginMappings = (mappings) => {
  *        How URLs are versioned for this entry point (defaults to "search_param")
  * @param {('none'|'inline'|'file'|'programmatic')} [entryPoint.sourcemaps]
  *        Sourcemap generation strategy for this entry point (defaults to "none")
+ * @param {boolean|object} [entryPoint.ribbon=false]
+ *        Inject a ribbon marking the page as non-production. Disabled by default
+ *        because the ribbon ends up inside the build directory: enable it on the
+ *        builds meant for a preview/review app, not on the production build.
+ *
+ *          ribbon: {
+ *            text: "preview",
+ *            color: "#7c3aed",
+ *            href: "https://github.com/org/repo/pull/42",
+ *          }
+ *
+ *        See startDevServer "ribbon" param for the full list of options.
  * @param {object} [entryPoint.injections]
  *        Values to inject into files, as { urlPattern: getInjections }.
  *        Keys are url patterns relative to sourceDirectoryUrl ("./index.html", "**\/*.js"),
@@ -12970,6 +13029,7 @@ const entryPointDefaultParams = {
   magicDirectoryIndex: undefined,
   directoryReferenceEffect: undefined,
   scenarioPlaceholders: undefined,
+  ribbon: false,
   injections: undefined,
   transpilation: {},
   preserveComments: undefined,
@@ -13024,6 +13084,7 @@ const prepareEntryPointBuild = async (
     magicDirectoryIndex,
     directoryReferenceEffect,
     scenarioPlaceholders,
+    ribbon,
     injections,
     transpilation,
     preserveComments,
@@ -13200,6 +13261,7 @@ const prepareEntryPointBuild = async (
       inlining: false,
       http,
       scenarioPlaceholders,
+      ribbon,
       packageSideEffects,
     }),
   ]);

package/dist/client/ribbon/ribbon.js

@@ -1,49 +1,117 @@
-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)";
+
+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 @@ 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/dist/js/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();
 
-const initDependencyStatus = ({ problems }) => {
+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),
   });
 };
 
@@ -58,4 +79,214 @@ const summarize = (outdatedList) => {
     .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;
+    }
+  }
+`;
+
 export { initDependencyStatus };