npm - @jsenv/navi - Versions diffs - 0.29.12 → 0.29.15 - Mend

@jsenv/navi 0.29.12 → 0.29.15

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/dist/jsenv_navi.js +311 -29
package/dist/jsenv_navi.js.map +31 -15
package/dist/jsenv_navi_side_effects.js +21 -0
package/dist/jsenv_navi_side_effects.js.map +2 -2
package/docs/AI_INSTRUCTIONS.md +4 -0
package/docs/css_architecture.md +53 -10
package/docs/scroll.md +250 -0
package/package.json +2 -2

package/dist/jsenv_navi.js CHANGED Viewed

@@ -12042,6 +12042,13 @@ const mergeActionParams = (currentParams, newParams) => {
   if (currentParams === NO_PARAMS) {
     return newParams;
   }
+  if (newParams === undefined) {
+    // Every control binds its action to its UI state signal; a control that carries
+    // no value (a button) has an undefined one. It contributes no params, which must
+    // not be confused with "the params are undefined" — the params bound by
+    // bindParams stay in place.
+    return currentParams;
+  }
   return mergeTwoJsValues(currentParams, newParams);
 };
@@ -13757,6 +13764,25 @@ const css$V = /* css */`
  * @param {Function} [options.onClose] - Callback when callout is closed
  * @param {boolean} [options.closeOnClickOutside] - Whether to close on outside clicks (defaults to true for "info" status)
  * @param {boolean} [options.debug=false] - Enable debug logging
+ *
+ * Positioning is also driven by attributes read on the anchor element itself
+ * (so markup can tune a callout without going through this function):
+ * - `data-callout-arrow-x="start" | "center" | "end"`: where the arrow points
+ *   horizontally along the anchor — `start`/`end` target the left/right edge of
+ *   the anchor's text content (inside its borders and padding), `center` targets
+ *   the middle of the anchor. Without it the arrow follows the anchor's computed
+ *   `text-align` (`center` → center, `right`/`end` → end, anything else → start),
+ *   so it lands where the text visually begins. The arrow is always clamped to
+ *   stay within the callout's own rounded corners, so a value pointing outside
+ *   the callout's width sticks to the nearest side.
+ * - `data-callout-position="top" | "bottom" | …`: preferred side of the anchor
+ *   (defaults to `"bottom"`, flipped when there isn't enough space).
+ * - `data-callout-position-fixed`: opt out of that flipping.
+ * - `data-callout-anchor="<selector>"`: point at an inner element instead of the
+ *   anchor itself.
+ * - `data-callout-point-to-border-box` / `data-callout-point-to-content-box`:
+ *   which box the callout aligns to.
+ * - `data-callout-viewport-spacing="<number>"`: minimum gap with the viewport edges.
  * @returns {Object} - Callout object with properties:
  *   - {Function} close - Function to close the callout
  *   - {Function} update - Function to update message and options
@@ -35835,10 +35861,13 @@ installImportMetaCssBuild(import.meta);const css$N = /* css */`
       --link-background: unset;
       --link-background-current: unset;
       --link-background-selected: light-dark(#bbdefb, #2563eb);
-      --link-color: rgb(0, 0, 238);
-      --link-color-visited: color-mix(in srgb, var(--link-color), black 40%);
+      --link-color: var(--navi-link-color);
+      --link-color-visited: var(
+        --navi-link-color-visited,
+        color-mix(in srgb, var(--link-color), black 40%)
+      );
-      --link-color-pressed: red;
+      --link-color-pressed: var(--navi-link-color-pressed);
       --link-text-decoration: underline;
       --link-text-decoration-hover: var(--link-text-decoration);
       --link-cursor: pointer;
@@ -35847,7 +35876,7 @@ installImportMetaCssBuild(import.meta);const css$N = /* css */`
       --link-current-indicator-size: 2px;
       --link-current-indicator-spacing: 0;
-      --link-current-indicator-color: rgb(205, 52, 37);
+      --link-current-indicator-color: var(--navi-link-current-indicator-color);
     }
   }
@@ -37767,7 +37796,16 @@ const FIXED_BAR_SPACE_CSS = /* css */ `
 // they overlap: the room to give back is the largest of them, not their sum,
 // and one leaving must leave the others' room in place.
 const sizeMapByArea = new Map();
+// What is currently on <html> for each area (absent = the variable is not set).
+// Writing the value that is already there would invalidate layout for nothing,
+// and several bars sharing an edge means most calls compute the same largest
+// size again — the ones for the smaller bars, and the second half of a page
+// transition.
+const writtenValueByArea = new Map();
+// A size that must land before the next paint: a render changed the bar, so
+// the room it takes is given back in that same commit and the content is never
+// painted under it.
 /**
  * @param {"top"|"bottom"|"left"|"right"} area
  * @param {Element} barElement - Which bar this size belongs to.
@@ -37775,6 +37813,65 @@ const sizeMapByArea = new Map();
  *   content.
  */
 const setFixedBarSpace = (area, barElement, size) => {
+  dropPendingSize(area, barElement);
+  storeSize(area, barElement, size);
+  writeSpace(area);
+};
+// A size nothing asked for, coming from a ResizeObserver. Writing the variable
+// resizes an ANCESTOR of the bars — the scroll container takes its padding
+// from it — and mutating layout from inside a resize callback is what makes
+// the browser report "ResizeObserver loop completed with undelivered
+// notifications". So the write waits for the frame that resize produced.
+// Queued here rather than deferred by each bar on its own, so the bars sharing
+// an edge resolve to a single write instead of one per bar.
+/**
+ * @param {"top"|"bottom"|"left"|"right"} area
+ * @param {Element} barElement - Which bar this size belongs to.
+ * @param {number} size - In px.
+ */
+const requestFixedBarSpace = (area, barElement, size) => {
+  let pendingSizeMap = pendingSizeMapByArea.get(area);
+  if (!pendingSizeMap) {
+    pendingSizeMap = new Map();
+    pendingSizeMapByArea.set(area, pendingSizeMap);
+  }
+  pendingSizeMap.set(barElement, size);
+  if (flushFrame !== null) {
+    return;
+  }
+  flushFrame = requestAnimationFrame(flushPendingSizes);
+};
+const pendingSizeMapByArea = new Map();
+let flushFrame = null;
+const flushPendingSizes = () => {
+  flushFrame = null;
+  for (const [area, pendingSizeMap] of pendingSizeMapByArea) {
+    for (const [barElement, size] of pendingSizeMap) {
+      storeSize(area, barElement, size);
+    }
+    writeSpace(area);
+  }
+  pendingSizeMapByArea.clear();
+};
+// What the bar itself just said wins over what its observer had queued about
+// it: a bar unmounting gives its room back, and a size queued for it before
+// that must not put it back.
+const dropPendingSize = (area, barElement) => {
+  const pendingSizeMap = pendingSizeMapByArea.get(area);
+  if (!pendingSizeMap) {
+    return;
+  }
+  pendingSizeMap.delete(barElement);
+  if (pendingSizeMap.size === 0) {
+    pendingSizeMapByArea.delete(area);
+  }
+};
+const storeSize = (area, barElement, size) => {
   let sizeMap = sizeMapByArea.get(area);
   if (!sizeMap) {
     sizeMap = new Map();
@@ -37785,7 +37882,10 @@ const setFixedBarSpace = (area, barElement, size) => {
   } else {
     sizeMap.set(barElement, size);
   }
+};
+const writeSpace = (area) => {
+  const sizeMap = sizeMapByArea.get(area);
   let largestSize = 0;
   for (const barSize of sizeMap.values()) {
     if (barSize > largestSize) {
@@ -37795,10 +37895,18 @@ const setFixedBarSpace = (area, barElement, size) => {
   const property = `--navi-fixed-bar-space-${area}`;
   const { style } = document.documentElement;
   if (sizeMap.size === 0) {
-    style.removeProperty(property);
-  } else {
-    style.setProperty(property, `${largestSize}px`);
+    if (writtenValueByArea.has(area)) {
+      writtenValueByArea.delete(area);
+      style.removeProperty(property);
+    }
+    return;
   }
+  const value = `${largestSize}px`;
+  if (writtenValueByArea.get(area) === value) {
+    return;
+  }
+  writtenValueByArea.set(area, value);
+  style.setProperty(property, value);
 };
 installImportMetaCssBuild(import.meta);/**
@@ -37974,27 +38082,40 @@ const FixedBar = ({
   // rebuilt as a calc() expression, so a size coming from anywhere — a prop, a
   // theme variable, the content itself — is reserved just the same, and each
   // `env()` inset stays the browser's business alone.
-  // And measured again whenever it changes: a ResizeObserver on the bar covers
-  // in one go a size prop that changes, content arriving or leaving, a font
-  // loading late, a rotation moving the notch.
   const vertical = area === "left" || area === "right";
   const {
     ref
   } = props;
+  const measureSpace = barElement => {
+    const {
+      width,
+      height
+    } = barElement.getBoundingClientRect();
+    return vertical ? width : height;
+  };
+  // Anything a render can change — a size prop, the children, a theme variable
+  // — is measured in that same commit, before paint: no frame where the
+  // content sits under the bar, and nothing written from inside an observer.
+  useLayoutEffect(() => {
+    const barElement = ref.current;
+    if (!barElement) {
+      return;
+    }
+    setFixedBarSpace(area, barElement, measureSpace(barElement));
+  });
+  // What no render caused: a font loading late, content arriving from outside,
+  // a rotation moving the notch. Measuring here is safe; the write is what has
+  // to wait, and fixed_bar_space.js is the one that holds it back.
   useLayoutEffect(() => {
     const barElement = ref.current;
     if (!barElement) {
       return undefined;
     }
-    const publishSize = () => {
-      const {
-        width,
-        height
-      } = barElement.getBoundingClientRect();
-      setFixedBarSpace(area, barElement, vertical ? width : height);
-    };
-    publishSize();
-    const resizeObserver = new ResizeObserver(publishSize);
+    const resizeObserver = new ResizeObserver(() => {
+      requestFixedBarSpace(area, barElement, measureSpace(barElement));
+    });
     resizeObserver.observe(barElement);
     return () => {
       resizeObserver.disconnect();
@@ -38799,7 +38920,7 @@ installImportMetaCssBuild(import.meta);const css$F = /* css */`
       --loader-color: var(--navi-loader-color);
       --border-color: var(--navi-control-border-color);
       --background-color: white;
-      --accent-color: light-dark(#4476ff, #3b82f6);
+      --accent-color: var(--navi-control-accent-color);
       --background-color-checked: var(--accent-color);
       --border-color-checked: var(--accent-color);
       --checkmark-color: white;
@@ -39539,7 +39660,7 @@ installImportMetaCssBuild(import.meta);const css$D = /* css */`
       --border-color: var(--navi-control-border-color);
       --background-color: white;
       --background-color-checked: var(--background-color);
-      --accent-color: light-dark(#4476ff, #3b82f6);
+      --accent-color: var(--navi-control-accent-color);
       --radiomark-color: var(--accent-color);
       --border-color-checked: var(--accent-color);
       --cursor: pointer;
@@ -40051,7 +40172,7 @@ installImportMetaCssBuild(import.meta);const css$C = /* css */`
       --font-family: var(--navi-control-font-family);
       --loader-color: var(--navi-loader-color);
-      --accent-color: rgb(24, 117, 255);
+      --accent-color: var(--navi-control-accent-color);
       --color-mix-light: black;
       --color-mix-dark: white;
       --color-mix: var(--color-mix-dark);
@@ -42884,6 +43005,13 @@ installImportMetaCssBuild(import.meta);/**
  * the map one would have drawn for a line, so it is drawn here and everything
  * below only ever knows about maps.
  *
+ * A travel is ONE BOX long, whatever the distance between the two slides on the
+ * map: the slide arriving is placed next to the one being left for the duration
+ * and put back where the map says afterwards, so a tab bar jumping from the
+ * first tab to the last shows those two and nothing else. Nobody wants to watch
+ * the slides in between fly past — least of all in a tab bar, where they are
+ * not a road one travels but places one goes straight to.
+ *
  * The slides live INSIDE the box, which is what makes this work for a popup: a
  * dialog and a popover are both promoted to the browser's top layer, so no
  * container of ours could ever hold two of them side by side and translate the
@@ -42987,6 +43115,18 @@ const css$z = /* css */`
            slides. */
         translate: var(--slide-offset, 0);
       }
+      /* Off stage: everything but the slide one is looking at and, while the
+         track moves, the slide one is leaving. A travel is one box long
+         whatever the distance on the map (the two are placed a box apart for
+         the occasion, see the layout effect), so the slides in between are
+         never crossed — but on a map wider than one box they would still sit
+         in the frame, and a tab bar jumping from the first tab to the last must
+         show those two and nothing else.
+         visibility, not display: this box is measured on its LARGEST slide, and
+         a slide taken out of the layout would take its size out with it. */
+      > [data-slide][data-slide-offstage] {
+        visibility: hidden;
+      }
       /* Nothing here for a slide not on screen: [inert] (set from JS) already
          takes it out of reach of the pointer, of Tab and of a screen reader —
          one attribute instead of pointer-events plus aria-hidden, and the only
@@ -43218,6 +43358,25 @@ const SlideContainer = ({
   // mid-travel would read a moving value.
   const offsetRef = useRef();
   const trackAnimationRef = useRef(null);
+  // Where the slides are while the track moves, which is not where the map says
+  // they are: the one being left stays put and the one arriving is placed ONE
+  // BOX away from it, whichever way the travel goes and however far apart the
+  // two are on the map. So a jump from the first tab to the last is one box of
+  // travel and the tabs in between are never seen flying past — and everything
+  // not in this map is off stage for the duration. Null at rest, when the map
+  // is the whole truth again (see settleTravel).
+  const stageRef = useRef(null);
+  // Which slide the last drawing put on screen: the current one at rest, the
+  // one being travelled TO while the track moves. What the next travel departs
+  // from, because it is what one is looking at.
+  const drawnAreaRef = useRef(undefined);
+  // Which way the travel about to be drawn goes, when whatever asked for it
+  // knows: a window stepping off its last slide comes back on its first, and
+  // only the press says that is a step forward — the map, read between those
+  // two places, says the opposite. Undefined for a travel asked for by name
+  // (--navi-go-to-slide, --navi-back), where the map is the only thing that
+  // knows and is right.
+  const travelStepRef = useRef(null);
   // What to do once the travel now starting is over, handed to the animation as
   // soon as there is one.
   const rollBackRef = useRef(null);
@@ -43319,6 +43478,52 @@ const SlideContainer = ({
     }
   };
+  // The travel is over: the stage is struck and every slide goes back where the
+  // map says it is. Nothing is seen moving for it — the slide on screen sits at
+  // the same place whatever the arrangement (its own offset and the track's are
+  // opposites and cancel out), and the others are off stage — as long as the
+  // two are written in one go, which is why this is done here rather than left
+  // to a render.
+  const settleTravel = () => {
+    const track = trackRef.current;
+    if (!track) {
+      return;
+    }
+    const {
+      slideElements,
+      placeOf
+    } = readMap();
+    const currentElement = slideElements.find(slideElement => slideElement.hasAttribute("data-current"));
+    if (!currentElement) {
+      return;
+    }
+    stageRef.current = null;
+    trackAnimationRef.current = null;
+    for (const slideElement of slideElements) {
+      const {
+        x,
+        y
+      } = placeOf.get(readArea(slideElement)) || {
+        x: 0,
+        y: 0
+      };
+      slideElement.style.setProperty("--slide-offset", `${x * 100}% ${y * 100}%`);
+      slideElement.toggleAttribute("data-slide-offstage", slideElement !== currentElement);
+    }
+    const currentArea = readArea(currentElement);
+    drawnAreaRef.current = currentArea;
+    const {
+      x,
+      y
+    } = placeOf.get(currentArea) || {
+      x: 0,
+      y: 0
+    };
+    const offset = `${-x * 100}% ${-y * 100}%`;
+    offsetRef.current = offset;
+    track.style.setProperty("--slide-container-offset", offset);
+  };
   // Everything positional is decided here, from the DOM, once per render: where
   // each slide stands on the map, which one is current, and how far the track
   // must be for that one to be the one on screen. Reading the DOM is what makes
@@ -43336,10 +43541,59 @@ const SlideContainer = ({
     // Nothing named, or a name nothing answers to: the first slide is the one
     // shown, the way a stack of pages opens on its first page.
     slideElements[0];
-    const currentPlace = placeOf.get(readArea(currentElement)) || {
+    const currentArea = readArea(currentElement);
+    const realPlaceOf = area => placeOf.get(area) || {
       x: 0,
       y: 0
     };
+    const durationMs = durationToMs(duration);
+    // Nothing is travelling, so nothing is staged: the picture to paint is the
+    // map itself, and a stage left over from a travel that has just been given
+    // up on would be painted instead of it.
+    if (noTravel) {
+      stageRef.current = null;
+    }
+    let stage = stageRef.current;
+    const drawnArea = stage ? stage.area : drawnAreaRef.current;
+    const travelStarts = !noTravel && durationMs > 0 && drawnArea !== undefined && drawnArea !== currentArea && slideElements.some(slideElement => readArea(slideElement) === drawnArea);
+    if (travelStarts) {
+      // Where the slide being left IS — the place the stage gave it if a travel
+      // was already playing (a press landing mid-travel departs from where the
+      // eye is, not from the map), its own place otherwise.
+      const departurePlace = stage ? stage.placeByArea.get(drawnArea) ?? realPlaceOf(drawnArea) : realPlaceOf(drawnArea);
+      const step = travelStepRef.current || {
+        x: Math.sign(realPlaceOf(currentArea).x - realPlaceOf(drawnArea).x),
+        y: Math.sign(realPlaceOf(currentArea).y - realPlaceOf(drawnArea).y)
+      };
+      // Kept, not replaced: the slides a chain of quick presses has already
+      // left behind are still trailing off screen, and taking them off stage
+      // now would blink them out mid-travel.
+      const placeByArea = new Map(stage?.placeByArea);
+      placeByArea.set(drawnArea, departurePlace);
+      const arrivalPlace = {
+        x: departurePlace.x + step.x,
+        y: departurePlace.y + step.y
+      };
+      // The cell the arriving slide takes, taken back from whoever was left
+      // standing on it: a travel turned around mid-flight comes back over
+      // ground it has just covered, and the slide it left there would be
+      // underneath the one arriving — two pictures in one box.
+      for (const [stagedArea, stagedPlace] of placeByArea) {
+        if (stagedArea !== drawnArea && stagedArea !== currentArea && stagedPlace.x === arrivalPlace.x && stagedPlace.y === arrivalPlace.y) {
+          placeByArea.delete(stagedArea);
+        }
+      }
+      placeByArea.set(currentArea, arrivalPlace);
+      stage = stageRef.current = {
+        placeByArea,
+        area: currentArea
+      };
+    }
+    // Said about the travel now being drawn and about no other: a re-render in
+    // the middle of one reads the stage back, which already knows.
+    travelStepRef.current = null;
+    const placeOfArea = area => stage && stage.placeByArea.get(area) || realPlaceOf(area);
+    const currentPlace = placeOfArea(currentArea);
     // A transfer waiting for a travel that never happened — a controlled
     // `current` the caller chose not to move: dropped, the focus has no
     // business going anywhere. The one for a travel that DID happen stays,
@@ -43355,17 +43609,18 @@ const SlideContainer = ({
     // and that one knows what was pressed.
     const focusIsLeaving = !focusHandOverRef.current && slideElements.some(slideElement => slideElement !== currentElement && slideElement.contains(document.activeElement));
     for (const slideElement of slideElements) {
+      const area = readArea(slideElement);
       const {
         x,
         y
-      } = placeOf.get(readArea(slideElement)) || {
-        x: 0,
-        y: 0
-      };
+      } = placeOfArea(area);
       slideElement.style.setProperty("--slide-offset", `${x * 100}% ${y * 100}%`);
       const isCurrent = slideElement === currentElement;
       slideElement.toggleAttribute("data-current", isCurrent);
       slideElement.toggleAttribute("data-slide-displaced", !isCurrent);
+      // On stage: the two ends of the travel while there is one, and the slide
+      // being shown when there is not.
+      slideElement.toggleAttribute("data-slide-offstage", stage ? !stage.placeByArea.has(area) : !isCurrent);
       if (isCurrent) {
         // Reachable again first, so the focus below has somewhere to land: an
         // inert element cannot take it.
@@ -43392,7 +43647,6 @@ const SlideContainer = ({
     // Where the track ends up, always — the animation below only covers the way
     // there, and when it is over this is what holds.
     track.style.setProperty("--slide-container-offset", offset);
-    const durationMs = durationToMs(duration);
     const travels = !noTravel && durationMs > 0 && offsetBefore !== undefined && offsetBefore !== offset;
     if (travels) {
       // The time it takes is the distance it has left to cover: a travel picked
@@ -43423,6 +43677,18 @@ const SlideContainer = ({
       if (pendingRollsRef.current.length) {
         hurryTravel(trackAnimationRef.current);
       }
+      // Arrived: the map is the truth again (see settleTravel). Attached before
+      // the window's own roll back just below, so the stage is struck first and
+      // whatever that one renders is drawn from the map.
+      trackAnimationRef.current.finished.then(settleTravel, () => {
+        // cancelled by the next travel — that one carries the stage on
+      });
+    } else if (stage && trackAnimationRef.current?.playState !== "running") {
+      // Staged with nothing left to play: a travel that was drawn and then had
+      // its animation taken away (a duration set to 0, a re-render landing
+      // between the two). Struck at once rather than left standing, since the
+      // thing it was standing for is over.
+      settleTravel();
     }
     // A window waiting for its travel to be over (see goToArea's own loop
     // branch): the animation says when, and says it about the move that just
@@ -43459,6 +43725,13 @@ const SlideContainer = ({
     for (const slideElement of slideElements) {
       slideElement.toggleAttribute("inert", slideElement !== currentElement);
     }
+    // What is on screen now, for the travel after this one to depart from.
+    // While a travel is playing the stage is the one that knows (it holds the
+    // slide being travelled TO, which is what one is looking at), so this is
+    // only ever written at rest.
+    if (!stageRef.current) {
+      drawnAreaRef.current = currentArea;
+    }
   });
   /**
@@ -43553,6 +43826,15 @@ const SlideContainer = ({
       ...cameFromRef.current,
       [area]: readArea(currentElement)
     };
+    // Which way this travel is drawn, said by what asked for it rather than
+    // read off the map: a window stepping off its last slide comes back on its
+    // first, and between those two places the map says "all the way back" when
+    // the press said "one forward". Nothing to say when the travel was asked
+    // for by name — there the map is the only one who knows.
+    travelStepRef.current = dx || dy ? {
+      x: Math.sign(dx),
+      y: Math.sign(dy)
+    } : null;
     if (loop) {
       // A window does not change slide, it rolls: the travel plays, and once it
       // is over the window is put back where it rests while whoever owns the