animate-text-weight 0.1.0 → 1.1.0

package/src/wave-nav.ts

@@ -0,0 +1,113 @@
+/*
+ * 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";
+
+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;
+}
+
+/** 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: Iterable<HTMLAnchorElement>,
+  options: WaveNavOptions = {}
+): () => void {
+  const pairs = [...links].flatMap((link) => {
+    const section = document.getElementById(link.hash.slice(1));
+    return section ? [{ link, section }] : [];
+  });
+
+  function setCurrent(index: number, on: boolean) {
+    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: HTMLElement) {
+    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/src/waves.ts

@@ -0,0 +1,73 @@
+/**
+ * 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 const other = (end: End): 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): End => (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): 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): 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): 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: Waves): number =>
+  (Number(waves.in) - Number(waves.out)) * Number(waves.way);