animate-text-weight 0.1.0 → 1.1.0

package/dist/wave-nav.d.ts

@@ -0,0 +1,12 @@
+export interface WaveNavOptions {
+    /** Toggled on the current link, as well as aria-current. */
+    linkClass?: string;
+    /** Toggled on the current link's section, which aria-current cannot mark. */
+    sectionClass?: string;
+}
+/**
+ * Mark the link of the section across the middle of the screen with
+ * aria-current="true". Each link's section is the element its hash names;
+ * a link without one is left out. Returns a function that stops following.
+ */
+export declare function waveNav(links: Iterable<HTMLAnchorElement>, options?: WaveNavOptions): () => void;

package/dist/wave-nav.js

@@ -0,0 +1,96 @@
+/*
+ * waveNav: a nav whose links follow the page, one section at a time.
+ *
+ * The current section is the one across the middle of the screen, worked out
+ * afresh from where things are on every scroll, never from what changed: a
+ * jump by Home or End passes every section in a few frames, and a switch that
+ * trusts enter and exit events is left on by the one that goes missing.
+ *
+ * A jump does not skip what it passes. The switch walks there one section at
+ * a time, each link on and then off again, and takes the next step once the
+ * wave has crossed the link it just switched on: its delay once per unit. So
+ * the links pick the wave up one from the other, and a jump sends one wave
+ * through the whole nav rather than a small one through each link.
+ *
+ * Optional, and apart from the library: nothing in index.ts imports it.
+ */
+import { UNIT } from "./index.js";
+/** At least a frame per step, so no link goes on and off before it is drawn. */
+const MIN_STEP = 17;
+/**
+ * Mark the link of the section across the middle of the screen with
+ * aria-current="true". Each link's section is the element its hash names;
+ * a link without one is left out. Returns a function that stops following.
+ */
+export function waveNav(links, options = {}) {
+    const pairs = [...links].flatMap((link) => {
+        const section = document.getElementById(link.hash.slice(1));
+        return section ? [{ link, section }] : [];
+    });
+    function setCurrent(index, on) {
+        const pair = pairs[index];
+        if (!pair)
+            return;
+        if (on)
+            pair.link.setAttribute("aria-current", "true");
+        else
+            pair.link.removeAttribute("aria-current");
+        if (options.linkClass)
+            pair.link.classList.toggle(options.linkClass, on);
+        if (options.sectionClass)
+            pair.section.classList.toggle(options.sectionClass, on);
+    }
+    /** The section across the middle, by index: -1 above the first, the length past the last. */
+    function getIndex() {
+        const middle = innerHeight / 2;
+        const below = pairs.findIndex(({ section }) => section.getBoundingClientRect().bottom > middle);
+        if (below === -1)
+            return pairs.length;
+        return pairs[below].section.getBoundingClientRect().top <= middle
+            ? below
+            : below - 1;
+    }
+    /** How long the wave takes to cross a link, in ms: its delay once per unit. */
+    function getCrossing(link) {
+        const delay = getComputedStyle(link)
+            .getPropertyValue("--animate-weight-delay")
+            .trim();
+        const milliseconds = parseFloat(delay) * (delay.endsWith("ms") ? 1 : 1000);
+        return link.querySelectorAll(`.${UNIT}`).length * milliseconds || 0;
+    }
+    let current = getIndex();
+    let target = current;
+    // The next step, while the wave is still crossing the last link.
+    let timer = 0;
+    setCurrent(current, true);
+    /** One section nearer the target, and the next once the wave is across. */
+    function update() {
+        timer = 0;
+        if (current === target)
+            return;
+        const next = current + Math.sign(target - current);
+        setCurrent(current, false);
+        setCurrent(next, true);
+        current = next;
+        const link = pairs[next]?.link;
+        timer = setTimeout(update, Math.max(MIN_STEP, link ? getCrossing(link) : 0));
+    }
+    function handleMove() {
+        target = getIndex();
+        if (!timer)
+            update();
+    }
+    // Scroll events already come once a frame. A section that changes height
+    // moves the ones below it without a scroll, and a resize moves the middle.
+    addEventListener("scroll", handleMove, { passive: true });
+    addEventListener("resize", handleMove);
+    const observer = new ResizeObserver(handleMove);
+    for (const { section } of pairs)
+        observer.observe(section);
+    return () => {
+        removeEventListener("scroll", handleMove);
+        removeEventListener("resize", handleMove);
+        observer.disconnect();
+        clearTimeout(timer);
+    };
+}

package/dist/waves.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Where a pointer element's two waves stand, and where a crossing sends them.
+ *
+ * The leading wave brings the weight up and the trailing one takes it away, so
+ * the text is at full weight between the two and a band of weight crosses it.
+ * Which way round the pair is travelling is the whole of the state: a visit
+ * runs them both to one end, the next visit runs them home again, and nothing
+ * is ever put back.
+ *
+ * Kept apart from the element it is written on, and out of the package's
+ * exports, because what it has to get right is arithmetic and not animation.
+ * A crossing that lands mid-band cannot be ordered against the frame the waves
+ * are on, so the rest it comes to must be right whatever they were doing: an
+ * entry always leaves the pair a whole crossing apart, which reads as full
+ * weight, and a leaving always brings them together, which reads as none. The
+ * waves decide how the text gets there and never whether.
+ */
+/** An end of the text, the way the stylesheet counts: 0 the start, 1 the far one. */
+export type End = "0" | "1";
+/** Which way round the pair is running: up from the start, or back down. */
+export type Way = "1" | "-1";
+/** Where each wave is headed, and which way round the two of them are going. */
+export interface Waves {
+    in: End;
+    out: End;
+    way: Way;
+}
+/** The other one of the two. */
+export declare const other: (end: End) => End;
+/**
+ * The end both waves are headed for, which is the one they are not resting at.
+ * Every visit runs them from the one to the other.
+ */
+export declare const target: (way: Way) => End;
+/**
+ * A pointer arriving: leading wave to the far end, trailing wave home.
+ *
+ * Both, every time, although one of the two is always already there. On a
+ * fresh visit the trailing wave is home and only the leading one moves, which
+ * opens the band; mid-band the leading one has arrived and only the trailing
+ * one moves, which sends the weight back in behind the pointer. Saying only
+ * the half that is needed means guessing which half that is, and a guess that
+ * misses writes a value already in place, which does nothing at all.
+ */
+export declare const entered: (waves: Waves) => Waves;
+/** A pointer leaving: the trailing wave after the leading one, to the same end. */
+export declare const left: (waves: Waves) => Waves;
+/**
+ * The pair turned round, ready for the next visit.
+ *
+ * Only where the two were sent to the same end, which is what a band that has
+ * come off leaves behind and the only state this may read. A pointer sitting
+ * on the text holds them at opposite ends, and turning the pair round under
+ * that would let go of all of it at once.
+ */
+export declare const settled: (waves: Waves) => Waves;
+/** What the text weighs once both waves have arrived: 1 all of it, 0 none. */
+export declare const weight: (waves: Waves) => number;

package/dist/waves.js

@@ -0,0 +1,52 @@
+/**
+ * Where a pointer element's two waves stand, and where a crossing sends them.
+ *
+ * The leading wave brings the weight up and the trailing one takes it away, so
+ * the text is at full weight between the two and a band of weight crosses it.
+ * Which way round the pair is travelling is the whole of the state: a visit
+ * runs them both to one end, the next visit runs them home again, and nothing
+ * is ever put back.
+ *
+ * Kept apart from the element it is written on, and out of the package's
+ * exports, because what it has to get right is arithmetic and not animation.
+ * A crossing that lands mid-band cannot be ordered against the frame the waves
+ * are on, so the rest it comes to must be right whatever they were doing: an
+ * entry always leaves the pair a whole crossing apart, which reads as full
+ * weight, and a leaving always brings them together, which reads as none. The
+ * waves decide how the text gets there and never whether.
+ */
+/** The other one of the two. */
+export const other = (end) => (end === "1" ? "0" : "1");
+/**
+ * The end both waves are headed for, which is the one they are not resting at.
+ * Every visit runs them from the one to the other.
+ */
+export const target = (way) => (way === "-1" ? "0" : "1");
+/**
+ * A pointer arriving: leading wave to the far end, trailing wave home.
+ *
+ * Both, every time, although one of the two is always already there. On a
+ * fresh visit the trailing wave is home and only the leading one moves, which
+ * opens the band; mid-band the leading one has arrived and only the trailing
+ * one moves, which sends the weight back in behind the pointer. Saying only
+ * the half that is needed means guessing which half that is, and a guess that
+ * misses writes a value already in place, which does nothing at all.
+ */
+export const entered = (waves) => ({
+    ...waves,
+    in: target(waves.way),
+    out: other(target(waves.way)),
+});
+/** A pointer leaving: the trailing wave after the leading one, to the same end. */
+export const left = (waves) => ({ ...waves, out: waves.in });
+/**
+ * The pair turned round, ready for the next visit.
+ *
+ * Only where the two were sent to the same end, which is what a band that has
+ * come off leaves behind and the only state this may read. A pointer sitting
+ * on the text holds them at opposite ends, and turning the pair round under
+ * that would let go of all of it at once.
+ */
+export const settled = (waves) => waves.in === waves.out ? { ...waves, way: waves.in === "1" ? "-1" : "1" } : waves;
+/** What the text weighs once both waves have arrived: 1 all of it, 0 none. */
+export const weight = (waves) => (Number(waves.in) - Number(waves.out)) * Number(waves.way);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "animate-text-weight",
-  "version": "0.1.0",
+  "version": "1.1.0",
   "description": "Animate short text between two weights of a variable font without moving a single line.",
   "license": "MIT",
   "author": "Tim Schoch",
@@ -14,6 +14,10 @@
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
     },
+    "./wave-nav": {
+      "types": "./dist/wave-nav.d.ts",
+      "default": "./dist/wave-nav.js"
+    },
     "./style.css": "./src/animateTextWeight.css"
   },
   "files": [
@@ -22,13 +26,17 @@
   ],
   "scripts": {
     "build": "tsc",
+    "test": "tsc && node --test test/band.test.mjs test/waves.test.mjs",
+    "test:browser": "tsc && node --test test/*.browser.test.mjs",
     "prepare": "husky && tsc",
-    "demo": "tsc && npx -y serve -l 3000 ."
+    "demo": "tsc && npx -y serve -l 3000 .",
+    "compare": "tsc && node scripts/compare.mjs"
   },
   "devDependencies": {
     "husky": "^9.1.7",
     "lint-staged": "^17.5.0",
     "prettier": "^3.9.6",
+    "puppeteer-core": "^25.12.0",
     "typescript": "^6.0.3"
   }
 }

package/src/animateTextWeight.css

@@ -7,9 +7,21 @@
  *   --animate-weight-to:   700;   the weight it animates to
  *   --animate-weight:      true;  on any state or ancestor: switch it on
  *
- * And two more if you want the text to arrive in a wave:
+ * And three more if you want the text to arrive in a wave:
  *   --animate-weight-by:    character;  one unit per character, not per line
  *   --animate-weight-delay: 40ms;       one unit waits this long after the one before it
+ *   --animate-weight-direction: end;    the wave runs the other way. Or
+ *                                       pointer, or scroll, or both: the
+ *                                       script points it where the pointer or
+ *                                       the page came from, every time it
+ *                                       moves, and the last to move has the
+ *                                       say.
+ *
+ * And two if you want the color to travel with the weight:
+ *   --animate-weight-color-from: #1c1c1c;  the color it animates from,
+ *                                          else the text color
+ *   --animate-weight-color-to:   #c8102e;  the color it animates to,
+ *                                          else the text color
  *
  * The script (index.ts) splits the element into one span per rendered
  * line, class .animate-text-weight-line, and in character mode splits each
@@ -61,12 +73,122 @@
   inherits: true;
   initial-value: 0s;
 }
+/*
+ * --animate-weight-direction is which end of the line the wave starts at: the
+ * one the text starts at, or the one it ends at. Logical, so right-to-left
+ * text waves right-to-left; in line mode the ends are the first and the last
+ * line instead.
+ *
+ * pointer and scroll hand the choice to the script. Name both and the script
+ * watches both, and whichever moved last has the say.
+ *
+ * It is deliberately not registered with @property. A registration takes one
+ * syntax, and the value is either one of four words or two of them at once;
+ * the loose "<custom-ident>+" that admits the pair is not what the style query
+ * further down compares against. Left unregistered, the query compares the
+ * words themselves, which is all this ever asked for.
+ *
+ * --atw-flip-in and --atw-flip-out are what the waits actually read: 0 counts
+ * from the start of the text, 1 counts from the far end. Numbers rather than
+ * words, and inherited rather than queried, because the script writes them
+ * while the pointer is already arriving. An inherited value reaches the units
+ * in the same pass that turns :hover on; a container query reaches them one
+ * pass later, by which time the visit runs the old way round.
+ */
+@property --atw-flip-in {
+  syntax: "<number>";
+  inherits: true;
+  initial-value: 0;
+}
+@property --atw-flip-out {
+  syntax: "<number>";
+  inherits: true;
+  initial-value: 0;
+}
+/*
+ * The two waves. Each is 0 before it has started and 1 once it has passed
+ * everything, and a unit is at full weight between the one and the other:
+ * --atw-wave-in brings the weight up, --atw-wave-out takes it away again.
+ *
+ * Two, so that the two fronts can be on the text at the same time. One wave
+ * has to arrive everywhere before it can turn round, which leaves the text
+ * sitting at full weight for a whole crossing while the far end waits its
+ * turn. Two waves let the second follow the first at a fixed distance, and
+ * what crosses the text is a band of weight rather than a tide that comes in
+ * and then goes out.
+ *
+ * One transition per line carries each, and every unit works its own share out
+ * of them. That is the whole reason they exist. A delay per unit would mean a
+ * unit that has not started yet has nothing running to turn round — switch a
+ * wave off while it is still waiting and the browser drops it where it stands,
+ * and that letter never moves at all. Brush past a link, or scroll a heading
+ * out of view mid-wave, and the wave breaks apart. Nothing here ever waits:
+ * every unit is reading numbers that are already moving, so a wave can be
+ * turned round at any moment and comes apart at none.
+ */
+@property --atw-wave-in {
+  syntax: "<number>";
+  inherits: true;
+  initial-value: 0;
+}
+@property --atw-wave-out {
+  syntax: "<number>";
+  inherits: true;
+  initial-value: 0;
+}
+/* A unit's share of each wave, which the weight below is the gap between. */
+@property --atw-rise {
+  syntax: "<number>";
+  inherits: false;
+  initial-value: 0;
+}
+@property --atw-fall {
+  syntax: "<number>";
+  inherits: false;
+  initial-value: 0;
+}
+/*
+ * Which way round the two waves are running: 1 up, -1 back down.
+ *
+ * A visit leaves both waves parked at the far end from the one it started at,
+ * and the next one runs them home again. So nothing is ever put back: the
+ * weight is the gap between the two waves whichever way they travel, and this
+ * is only the sign that keeps the gap positive. Putting them back instead
+ * would mean a second crossing of nothing to look at between every two visits.
+ */
+@property --atw-way {
+  syntax: "<number>";
+  inherits: true;
+  initial-value: 1;
+}
+/*
+ * The page's switch again, as a number that can be transitioned, so that the
+ * script hears it change. A pointer-following element's waves are the script's
+ * to send, and a hover is not the only thing that switches it: a class or the
+ * page can hold it on while the pointer comes and goes. The transition is a
+ * doorbell and nothing reads the value.
+ */
+@property --atw-on {
+  syntax: "<number>";
+  inherits: false;
+  initial-value: 0;
+}
 /* How many delays this unit waits: the count of the one before it, plus one. */
 @property --atw-delay-count {
   syntax: "<number>";
   inherits: false;
   initial-value: 0;
 }
+/*
+ * The count of the last unit of the wave, which is how long the wave is. Set
+ * on whatever holds the units — the line in character mode, the element in
+ * line mode — and read by each of them to count from the far end.
+ */
+@property --atw-delay-total {
+  syntax: "<number>";
+  inherits: true;
+  initial-value: 0;
+}
 /* The width a line is held at. */
 @property --atw-width {
   syntax: "<length>";
@@ -76,10 +198,47 @@
 
 :root {
   --animate-weight-duration: 300ms;
-  --animate-weight-easing: ease;
+  /*
+   * Flat, because this shapes the wave's travel and not one unit's own change.
+   * A curve that is slow at both its ends crawls into the top and crawls back
+   * out of it, and the two together read as a pause at full weight.
+   */
+  --animate-weight-easing: linear;
+  /*
+   * The least the trailing wave ever follows the leading one by. Without a
+   * floor, a link brushed past in a moment gets a band a letter wide and shows
+   * nothing; with one, the pointer can be long gone and the band still crosses.
+   */
+  --atw-wave-min-delay: 400ms;
 }
 
 .animate-text-weight-line {
+  /*
+   * How long the whole wave takes: the last unit's wait, plus the time that
+   * unit then spends moving. Never zero, or the wave below would have nothing
+   * to cross — reduced motion takes both of these to 0s.
+   */
+  --atw-span: max(
+    1ms,
+    calc(var(--atw-delay-total) * var(--animate-weight-delay) + var(--animate-weight-duration))
+  );
+  /*
+   * The script's own switches, in their own properties rather than in
+   * --animate-weight, because the page writes that one and the two would take
+   * it off each other. Unset, the leading wave is the page's to switch and the
+   * trailing one stays put; set, they say outright where each wave is headed.
+   */
+  --atw-wave-in: var(--atw-in, 0);
+  --atw-wave-out: var(--atw-out, 0);
+  /*
+   * The two moving parts. The trailing wave's delay is how far it follows the
+   * leading one by, which the script works out per visit and writes; a page
+   * that never leaves it alone never sets it, and the two run together.
+   */
+  transition:
+    --atw-wave-in var(--atw-span) var(--animate-weight-easing),
+    --atw-wave-out var(--atw-span) var(--animate-weight-easing) var(--atw-out-wait, 0s),
+    --atw-on 1ms;
   /* A line can get wider or narrower, never reflow. */
   white-space: nowrap;
   /* Fractional glyph advances, so Firefox does not snap letters mid-tween. */
@@ -166,14 +325,103 @@
   /*
    * Clamped, because an easing may overshoot: the spacing below stops at the
    * last stop, so an unclamped weight would keep going and break the width.
+   *
+   * Rounded to a whole weight, because Chrome (153, macOS, 2x screen) now and
+   * then draws a letter whose weight is a fresh fraction every frame with the
+   * wrong one for a single frame: mid-tween it flashes bold or light and is
+   * back the next. Plain spans tweening font-weight do it too, so it is not
+   * the waves. Whole weights are a few hundred values, the same ones every
+   * visit, and one weight is far below what the eye or the width can tell.
+   */
+  font-weight: round(
+    calc(
+      var(--atw-from) + (var(--atw-to) - var(--atw-from)) *
+        clamp(0, var(--animate-weight-progress), 1)
+    ),
+    1
+  );
+  /*
+   * This unit's own share of each wave, worked out afresh every frame rather
+   * than transitioned: how far that wave has come, less what this unit waits
+   * for it, over the time this unit then takes.
+   *
+   * A flip of 0 leaves the count where it is; a flip of 1 turns it into
+   * (total - count), which is the same wave counted from the far end. Read
+   * here, in the open, so a wave already running turns round when its flip
+   * does — nothing is latched at the moment a tween starts, because no tween
+   * starts here.
+   */
+  --atw-wait-in: calc(
+    (
+        var(--atw-delay-count) + var(--atw-flip-in) *
+          (var(--atw-delay-total) - 2 * var(--atw-delay-count))
+      ) * var(--animate-weight-delay)
+  );
+  --atw-wait-out: calc(
+    (
+        var(--atw-delay-count) + var(--atw-flip-out) *
+          (var(--atw-delay-total) - 2 * var(--atw-delay-count))
+      ) * var(--animate-weight-delay)
+  );
+  /*
+   * tan(atan2(a, b)) is a / b. A time over a time is typed arithmetic, which
+   * Firefox does not ship yet: it drops the division silently and nothing
+   * moves. atan2 takes two times and tan hands back a plain number.
    */
-  font-weight: calc(
-    var(--atw-from) + (var(--atw-to) - var(--atw-from)) *
-      clamp(0, var(--animate-weight-progress), 1)
+  --atw-rise: clamp(
+    0,
+    tan(
+      atan2(
+        var(--atw-wave-in) * var(--atw-span) - var(--atw-wait-in),
+        max(1ms, var(--animate-weight-duration))
+      )
+    ),
+    1
+  );
+  --atw-fall: clamp(
+    0,
+    tan(
+      atan2(
+        var(--atw-wave-out) * var(--atw-span) - var(--atw-wait-out),
+        max(1ms, var(--animate-weight-duration))
+      )
+    ),
+    1
+  );
+  /*
+   * Full weight between the one wave and the other, and --atw-way to keep that
+   * gap the right way up when the pair is running back down.
+   *
+   * Clamped low as well as high, because the two waves need not run the same
+   * way round, and a unit the trailing wave reaches before the leading one
+   * would otherwise go past light and out the other side.
+   */
+  --animate-weight-progress: clamp(
+    0,
+    calc((var(--atw-rise) - var(--atw-fall)) * var(--atw-way)),
+    1
+  );
+}
+
+/*
+ * The color, if the element asks for one. An end left unset is the text color.
+ *
+ * It is read off the unit's own progress rather than transitioned itself, so
+ * it takes the curve, the duration and the delay the weight already has, and
+ * in character mode it arrives as the same wave. oklab because that is the
+ * space a plain color transition interpolates in.
+ *
+ * Not registered with @property, on purpose: a registration needs an
+ * initial-value, and that would hand every unit two colors no page asked for.
+ * The fallback is currentColor, which inside color is the inherited color, so
+ * an element that sets neither mixes its own color with itself and keeps it.
+ */
+.animate-text-weight-unit {
+  color: color-mix(
+    in oklab,
+    var(--animate-weight-color-to, currentColor) calc(clamp(0, var(--animate-weight-progress), 1) * 100%),
+    var(--animate-weight-color-from, currentColor)
   );
-  transition: --animate-weight-progress var(--animate-weight-duration) var(--animate-weight-easing);
-  /* After the shorthand, which would reset it. */
-  transition-delay: calc(var(--atw-delay-count) * var(--animate-weight-delay));
 }
 
 /*
@@ -198,10 +446,40 @@
   );
 }
 
-/* The switch. The element is the unit's style container. */
+/*
+ * The page's switch, which comes after the line's own rule so that it wins
+ * while the page holds it on. The element is the line's style container.
+ *
+ * --atw-in still ahead of it, so that a script following the pointer keeps the
+ * last word either way: it hears the switch through --atw-on and sends the
+ * waves itself, so a band coming off is never cut short by the switch.
+ */
 @container style(--animate-weight: true) {
+  .animate-text-weight-line {
+    --atw-wave-in: var(--atw-in, 1);
+    --atw-on: 1;
+  }
+}
+
+/*
+ * The wave the other way round: a unit waits for the ones behind it instead of
+ * the ones in front of it, so the last one moves first. The counts are not
+ * rewritten for this — they are read backwards from the far end, which is what
+ * --atw-delay-total holds. So direction can change at any time, on a state or
+ * a media query, and nothing has to be measured again.
+ *
+ * This is the stylesheet's own end, and only that. A separate property,
+ * because the script must not overwrite the word the stylesheet asked for —
+ * pointer and scroll write the flips on the element instead, where they reach
+ * the units by inheritance and this rule never matches.
+ *
+ * Both waves, because a page that fixes an end wants the whole thing that way
+ * round; the two only part company when the pointer sends them.
+ */
+@container style(--animate-weight-direction: end) {
   .animate-text-weight-unit {
-    --animate-weight-progress: 1;
+    --atw-flip-in: 1;
+    --atw-flip-out: 1;
   }
 }