@react-x11/components 0.8.0 → 0.10.0

package/src/internal/prewarm.ts

@@ -0,0 +1,45 @@
+// A font family, warmed before the first layout sets text in it.
+import { useMemo } from 'react';
+import { useApp } from 'react-x11';
+
+/** The one method this needs of `app.fonts`, which ntk's FontManager has
+ *  from the release that added it, and other font managers may not. */
+interface PrewarmingFonts {
+  prewarm?: (family: string) => void;
+}
+
+/**
+ * Start matching `family`'s faces now, off the event loop, so that the first
+ * layout setting text in it takes the answer instead of stalling on the
+ * system's font matcher — ntk's `FontManager#prewarm`. fontconfig answers in
+ * 20–40 ms on a Linux desktop and in 80–150 on XQuartz, and nothing warms a
+ * family but sans-serif until a layout asks for it.
+ *
+ * Called while rendering, as React's own resource hints are: a component
+ * renders ahead of the frame that lays it out, and a long document's render
+ * is hundreds of milliseconds of head start that an effect would give away.
+ * Once per family; nothing where the app's fonts have nothing to look up
+ * (fonts in memory, a native text engine) or predate the method.
+ */
+export function useFontPrewarm(family: string | null | undefined): void {
+  const fonts = (useApp() as { fonts?: PrewarmingFonts } | null)?.fonts;
+  useMemo(() => {
+    if (family) fonts?.prewarm?.(family);
+  }, [fonts, family]);
+}
+
+/** The font family a style names, read the way core flattens one — the last
+ *  entry of an array that names it wins — or `fallback`. */
+export function styleFamily(style: unknown, fallback: string): string {
+  let family = fallback;
+  const visit = (entry: unknown): void => {
+    if (Array.isArray(entry)) {
+      for (const e of entry) visit(e);
+    } else if (entry && typeof entry === 'object') {
+      const named = (entry as { fontFamily?: unknown }).fontFamily;
+      if (typeof named === 'string') family = named;
+    }
+  };
+  visit(style);
+  return family;
+}

package/src/internal/scroll.ts

@@ -101,8 +101,9 @@ export interface Reveal {
   /** Scroll the pane, recording that this component is the one that asked. */
   scrollTo(y: number): void;
   /** An `onScroll` arrived. One this component did not ask for is the user
-   *  taking over, and it cancels whatever was owed. */
-  heard(scrollY: number): void;
+   *  taking over, and it cancels whatever was owed. Answers whether it was
+   *  this component's own. */
+  heard(scrollY: number): boolean;
 }
 
 /**
@@ -336,7 +337,7 @@ export function useReveal(sources: RevealSources): Reveal {
     [retry],
   );
 
-  const heard = useCallback((scrollY: number): void => {
+  const heard = useCallback((scrollY: number): boolean => {
     // A scroll this component did not ask for ends the whole chase, not just
     // the outstanding half of it. Within half a pixel is ours: the payload
     // is the device offset divided back to logical, and at a fractional
@@ -349,6 +350,7 @@ export function useReveal(sources: RevealSources): Reveal {
       owedShift.current = 0;
     }
     asked.current = null;
+    return ours;
   }, []);
 
   // One stable object, not a fresh literal per render: callbacks built on

package/src/internal/sdf.ts

@@ -0,0 +1,227 @@
+// A label's raster as a signed distance field: what lets one raster serve a
+// name at every size a zoom passes through, and a halo of any width. Under
+// the GL labels of both `<Map>` (`src/maps/gl/text.ts`) and `<Flow>`
+// (`src/flow/gl/text.ts`), which is why it is here rather than in either.
+//
+// The text engine sets a string as coverage — alpha, antialiased — at one
+// base size. Each texel here becomes its distance to the glyphs' edge,
+// encoded in a byte so that `SDF_EDGE` is the edge itself, more is inside
+// and less is outside:
+//
+//   byte = 255 · (1 − d / radius − SDF_CUTOFF),   d > 0 outside
+//
+// so a field reaches `radius · (1 − SDF_CUTOFF)` texels past the glyphs
+// before it saturates at 0 — the room a halo has to grow into — and
+// `radius · SDF_CUTOFF` into them.
+//
+// The distance is the exact Euclidean one, started at the edge by what the
+// coverage says: an antialiased texel half covered sits on the edge, one a
+// quarter covered a quarter of a texel outside it. That sub-texel start is
+// what keeps a field set at 16 pixels from drawing a lumpy stroke at 40.
+//
+// **Only where it can change a byte.** A field is set the first time its
+// string is drawn, so its cost is how late a label appears. Outside the
+// glyphs the distance is Felzenszwalb and Huttenlocher's linear-time
+// transform — but only over the window a field reaches round the ink, the
+// rows that hold ink first and then the window's columns, since past the
+// reach every byte is 0 and every source is inside it. Inside, a field
+// saturates `radius · SDF_CUTOFF` texels in (1.5 at Flow's margin, 2.25 at
+// a map's), so the nearest texel less than half covered is found by
+// searching the few rings round each texel inside, not by a second
+// transform over the whole raster. Byte for byte what the two whole
+// transforms gave, at half the cost: measured over DirectWrite's coverage
+// of 520 labels, 262 → 140 µs a field at Flow's margin and 626 → 311 at a
+// map's.
+
+/** The fraction of the byte range spent inside the glyphs. */
+export const SDF_CUTOFF = 0.25;
+
+/** The byte value of the glyphs' edge, as a fraction: `1 − SDF_CUTOFF`. */
+export const SDF_EDGE = 1 - SDF_CUTOFF;
+
+/**
+ * Device pixels outside a field's outline that its ink's edge is drawn. A
+ * text engine darkens stems at small sizes; a field thresholded at half
+ * coverage gives that back, and a string drawn from one looks a weight
+ * lighter than the same string set. Both GL label shaders draw it.
+ */
+export const SDF_INK_BIAS_PX = 0.15;
+
+/** "No edge in reach": far past any raster's squared diagonal, and small
+ *  enough that `FAR + q²` is still exact in a double, so two of them cross
+ *  where two parabolas of one height do. */
+const FAR = 1e10;
+
+/**
+ * Each coverage byte's squared distance to the edge *inside* its own
+ * texel: (a − ½)² where more than half covered, 0 where not — a texel less
+ * than half covered is outside, where an inside distance ends — and FAR
+ * where whole.
+ */
+const INSIDE = new Float64Array(256);
+for (let a8 = 1; a8 < 255; a8++) {
+  const d = 0.5 - a8 / 255;
+  INSIDE[a8] = d < 0 ? d * d : 0;
+}
+INSIDE[255] = FAR;
+
+/** Scratch, grown to the largest raster seen and reused. */
+let outer = new Float64Array(0);
+let f = new Float64Array(0);
+let g = new Float64Array(0);
+let z = new Float64Array(0);
+let v = new Int32Array(0);
+
+function grow(texels: number, line: number): void {
+  if (outer.length < texels) outer = new Float64Array(texels);
+  if (f.length < line) {
+    f = new Float64Array(line);
+    g = new Float64Array(line);
+    z = new Float64Array(line + 1);
+    v = new Int32Array(line);
+  }
+}
+
+/**
+ * The squared distance transform of `length` values of `grid` from
+ * `offset`, `stride` apart, in place: each becomes the least
+ * `grid[r] + (q − r)²` — the lower envelope of parabolas rooted at every
+ * texel. `g` holds each parabola's `grid[r] + r²`, so where two cross is
+ * one division.
+ */
+function transform1d(
+  grid: Float64Array,
+  offset: number,
+  stride: number,
+  length: number,
+): void {
+  let k = 0;
+  v[0] = 0;
+  z[0] = -Infinity;
+  z[1] = Infinity;
+  f[0] = grid[offset];
+  g[0] = f[0];
+  for (let q = 1, at = offset + stride; q < length; q++, at += stride) {
+    const fq = grid[at];
+    f[q] = fq;
+    const gq = fq + q * q;
+    g[q] = gq;
+    let s: number;
+    for (;;) {
+      const r = v[k];
+      s = (gq - g[r]) / (2 * (q - r));
+      if (s > z[k] || k === 0) break;
+      k--;
+    }
+    k++;
+    v[k] = q;
+    z[k] = s;
+    z[k + 1] = Infinity;
+  }
+  k = 0;
+  for (let q = 0, at = offset; q < length; q++, at += stride) {
+    while (z[k + 1] < q) k++;
+    const r = v[k];
+    const d = q - r;
+    grid[at] = f[r] + d * d;
+  }
+}
+
+/**
+ * The field of a `width` × `height` raster whose coverage is `alpha`
+ * (0-255), read every `step` bytes from `start` — so an RGBA readback is
+ * read in place, `step` 4 and `start` 3, and an engine's own coverage with
+ * `step` 1 and `start` 0. One byte a texel, see the top of this file for
+ * the encoding.
+ */
+export function distanceField(
+  alpha: Uint8Array,
+  width: number,
+  height: number,
+  radius: number,
+  step = 4,
+  start = 3,
+): Uint8Array {
+  const texels = width * height;
+  grow(texels, Math.max(width, height));
+  // Zeroed: a byte nothing below writes is as far outside as a field sees.
+  const out = new Uint8Array(texels);
+  let minX = width;
+  let maxX = -1;
+  let minY = height;
+  let maxY = -1;
+  for (let y = 0, i = 0, a = start; y < height; y++) {
+    for (let x = 0; x < width; x++, i++, a += step) {
+      const a8 = alpha[a];
+      if (a8 === 0) {
+        outer[i] = FAR;
+        continue;
+      }
+      if (x < minX) minX = x;
+      if (x > maxX) maxX = x;
+      if (y < minY) minY = y;
+      if (y > maxY) maxY = y;
+      if (a8 === 255) {
+        outer[i] = 0;
+        continue;
+      }
+      // Partly covered: on the edge, off it by how far from half covered.
+      const d = 0.5 - a8 / 255;
+      outer[i] = d > 0 ? d * d : 0;
+    }
+  }
+  if (maxX < 0) return out;
+
+  // Outside: the window the field reaches round the ink. Every source is
+  // in it, so what the transform computes there is exact, and past it every
+  // byte is 0. The rows with ink first — every source is on one — then
+  // every column of the window.
+  const reach = Math.ceil(radius * (1 - SDF_CUTOFF)) + 1;
+  const x0 = Math.max(0, minX - reach);
+  const x1 = Math.min(width - 1, maxX + reach);
+  const y0 = Math.max(0, minY - reach);
+  const y1 = Math.min(height - 1, maxY + reach);
+  for (let y = minY; y <= maxY; y++) {
+    transform1d(outer, y * width + x0, 1, x1 - x0 + 1);
+  }
+  for (let x = x0; x <= x1; x++) {
+    transform1d(outer, y0 * width + x, width, y1 - y0 + 1);
+  }
+
+  // Inside, the field saturates this many rings in.
+  const deep = Math.ceil(radius * SDF_CUTOFF);
+  for (let y = y0; y <= y1; y++) {
+    for (let x = x0, i = y * width + x0; x <= x1; x++, i++) {
+      // Outside the ink, or in it: never both.
+      const o = outer[i];
+      let d: number;
+      if (o > 0) {
+        d = Math.sqrt(o);
+      } else {
+        // The least (a − ½)² + distance² over the texels round it, ring by
+        // ring, until no ring further out could be nearer — or the field
+        // has saturated, where the exact answer and this one are both 255.
+        let best = INSIDE[alpha[start + i * step]];
+        for (let k = 1; k <= deep && best > k * k; k++) {
+          for (let yy = y - k; yy <= y + k; yy++) {
+            if (yy < 0 || yy >= height) continue;
+            const dy2 = (yy - y) * (yy - y);
+            // a ring's top and bottom rows whole, its sides two texels
+            const across = yy === y - k || yy === y + k ? 1 : 2 * k;
+            for (let xx = x - k; xx <= x + k; xx += across) {
+              if (xx < 0 || xx >= width) continue;
+              const dx = xx - x;
+              const m =
+                INSIDE[alpha[start + (yy * width + xx) * step]] + dx * dx + dy2;
+              if (m < best) best = m;
+            }
+          }
+        }
+        d = -Math.sqrt(best);
+      }
+      const value = Math.round(255 - 255 * (d / radius + SDF_CUTOFF));
+      out[i] = value < 0 ? 0 : value > 255 ? 255 : value;
+    }
+  }
+  return out;
+}

package/src/internal/splice.ts

@@ -0,0 +1,25 @@
+/**
+ * `target.splice(from, removed, ...items)`, for any number of items.
+ *
+ * A spread argument list lives on the stack, and somewhere past a hundred
+ * thousand items it throws `RangeError: Maximum call stack size exceeded` —
+ * a pasted log, or a file replaced whole, is that many lines. Past a few
+ * thousand the array is rebuilt in place instead: whoever holds `target`
+ * keeps holding it, which is the whole reason it is spliced rather than
+ * replaced.
+ */
+export function spliceAll<T>(
+  target: T[],
+  from: number,
+  removed: number,
+  items: readonly T[],
+): void {
+  if (items.length <= 4096) {
+    target.splice(from, removed, ...items);
+    return;
+  }
+  const tail = target.slice(from + removed);
+  target.length = from;
+  for (let i = 0; i < items.length; i++) target.push(items[i]);
+  for (let i = 0; i < tail.length; i++) target.push(tail[i]);
+}

package/src/internal/window.ts

@@ -30,7 +30,8 @@
 //     forces them out, trailing side first — a direction reversal lands on
 //     rows still mounted instead of rebuilding them. The budget caps what a
 //     render can be asked to carry: the on-screen slice plus `prefetch` rows
-//     each side.
+//     each side — at any speed, which is why a row is measured on its way
+//     out when nothing has measured it yet.
 //   - **Skeletons.** A scroll that outruns everything — a thumb dragged
 //     across the list, a flick past the band — floods the window with rows
 //     no single render can build in time. Those render as *skeletons*: the
@@ -164,6 +165,18 @@ export interface VirtualWindowInputs {
    *  settled. `BURST_BUDGET` / `SETTLE_BUDGET` are the defaults. */
   burstBudget: number;
   settleBudget: number;
+  /**
+   * Record the height the drawn row `id`, at `index`, is laid out at in the
+   * index, now; answer whether the index has a real height for it after.
+   * The trim asks before it drops a row the measure tick has not reached
+   * (see the budget below), during render — so no nudge and no re-render:
+   * the row is still laid out at exactly that height, and nothing on screen
+   * moves until the spacer takes its place. `false` for a row with no
+   * honest measurement to give, which keeps it mounted. `viewport` is the
+   * event-fresh one (`viewRef`), for a component whose rows are laid out
+   * against it.
+   */
+  measure?: (id: RowKey, index: number, viewport: VirtualViewport) => boolean;
 }
 
 export interface VirtualWindow {
@@ -370,6 +383,7 @@ export function useVirtualWindow(inputs: VirtualWindowInputs): VirtualWindow {
     threshold,
     burstBudget,
     settleBudget,
+    measure,
   } = inputs;
   const count = rows.length;
 
@@ -448,15 +462,32 @@ export function useVirtualWindow(inputs: VirtualWindowInputs): VirtualWindow {
       // row laid out taller than the index believes contributes its real
       // height while mounted and its guessed one once dropped, so cutting
       // it silently shrinks the content above the viewport and the view
-      // yanks up by the difference with no debt left to put it right. Held
-      // a render or two longer, it gets measured, and the next trim takes
-      // it cleanly.
+      // yanks up by the difference with no debt left to put it right.
+      //
+      // So a row the index has no number for is measured *here*, where it
+      // is still laid out (`measure`): once the index holds the height it
+      // is drawn at, the spacer that replaces it is exactly as tall, and it
+      // goes like any other. Waiting for the measure tick instead is only
+      // safe while the tick runs — and a flick defers every measurement to
+      // the settle, so a long one downward trimmed nothing at all and the
+      // window grew by every row it passed: 1,250 rows mounted four seconds
+      // into a trackpad fling, each frame laying all of them out. A row the
+      // last render did not build in full needs nothing: a skeleton is
+      // drawn at the index's height, and a row never drawn is not in the
+      // layout at all. What cannot be measured — a row not laid out yet, or
+      // laid out against a grid it is about to leave — is held a render or
+      // two longer, as before.
       const budget = coreLast - coreFirst + 2 * prefetch;
       let excess = last - first - budget;
       if (excess > 0) {
+        const known = (i: number): boolean =>
+          exact ||
+          heights.isMeasured(i) ||
+          !real.current.has(rows[i].id) ||
+          measure?.(rows[i].id, i, viewRef.current) === true;
         const cutAbove = (want: number): number => {
           let k = 0;
-          while (k < want && (exact || heights.isMeasured(first + k))) k++;
+          while (k < want && known(first + k)) k++;
           return k;
         };
         const aboveExtra = coreFirst - first;