@react-x11/components 0.9.0 → 0.10.0

package/src/internal/markdown/parse.ts

@@ -181,31 +181,168 @@ function indentOf(line: string): number {
 
 export function parse(source: string, options: ParseOptions = {}): Document {
   const partial = options.partial !== false;
+  const isComponent = options.isComponent ?? NO_COMPONENTS;
+  const expressions = options.expressions === true;
   const normalized = source.replace(/\r\n?/g, '\n');
   const lines = normalized.split('\n').map(expandLeadingTabs);
+  const previous = options.previous;
+  const was = previous ? resumable.get(previous) : undefined;
+  // Not with components: an open tag looks for its close to the end of the
+  // document (`componentCloseLine`), so a close added anywhere below can
+  // change what it is, and the block before an edit is no longer settled.
+  if (
+    previous &&
+    was &&
+    was.partial === partial &&
+    was.expressions === expressions &&
+    isComponent === NO_COMPONENTS &&
+    was.isComponent === NO_COMPONENTS
+  ) {
+    return resume(previous, was, lines);
+  }
   const blocks: BlockNode[] = [];
   const ranges: Array<[number, number]> = [];
-  parseBlocks(
+  const blanks = new Uint8Array(lines.length);
+  parseBlocks(lines, partial, blocks, ranges, isComponent, expressions, {
+    from: 0,
+    blanks,
+  });
+  return remember(
+    { blocks, raws: ranges.map(([a, b]) => lines.slice(a, b).join('\n')) },
+    { lines, ranges, blanks, partial, isComponent, expressions },
+  );
+}
+
+// --- resuming --------------------------------------------------------------
+
+/**
+ * What a parse leaves for the next parse of the same document to start from
+ * (`ParseOptions.previous`).
+ *
+ * The block loop carries one thing from a block to the next, the paragraph
+ * it is gathering, and it looks only forwards: a block's extent is decided
+ * by the lines up to the first line of the block after it. So `blanks`
+ * marks the lines where the loop stood on a blank line at the top level with
+ * no paragraph open. Two parses standing on such a line, with the same lines
+ * from there to the end, produce the same blocks from there on. That is the
+ * point where an edit's re-parse can stop and take the rest from before.
+ */
+interface Resumable {
+  lines: string[];
+  /** each top-level block's [start, endExcl) line range */
+  ranges: Array<[number, number]>;
+  /** 1 on each line where the top-level loop stood blank with no paragraph */
+  blanks: Uint8Array;
+  partial: boolean;
+  isComponent: (name: string) => boolean;
+  expressions: boolean;
+}
+
+/** Kept beside the documents rather than in them, so a Document stays the
+ *  plain data every caller and test compares. */
+const resumable = new WeakMap<Document, Resumable>();
+
+function remember(doc: Document, state: Resumable): Document {
+  resumable.set(doc, state);
+  return doc;
+}
+
+/**
+ * Parse `lines` as an edit of `previous`: from one block before the first
+ * line that changed, until the loop stands where the previous parse stood
+ * in the lines the edit left alone — or to the end, when it never does (an
+ * unclosed fence swallows the rest of a document either way).
+ */
+function resume(previous: Document, was: Resumable, lines: string[]): Document {
+  const old = was.lines;
+  const oldN = old.length;
+  const n = lines.length;
+  const shortest = Math.min(oldN, n);
+  let first = 0;
+  while (first < shortest && old[first] === lines[first]) first += 1;
+  if (first === oldN && first === n) return previous;
+  // lines at the end the edit did not touch, never counting the prefix twice
+  let same = 0;
+  while (
+    same < shortest - first &&
+    old[oldN - 1 - same] === lines[n - 1 - same]
+  ) {
+    same += 1;
+  }
+  const shift = n - oldN;
+  const suffix = n - same;
+
+  // The first block that reaches the change, and the one before it: a
+  // block's extent is decided by the lines up to the next block's first —
+  // a list looks past blank lines to see whether it goes on — so the block
+  // before the first one touched cannot have depended on the change.
+  const { ranges } = was;
+  let lo = 0;
+  let hi = ranges.length;
+  while (lo < hi) {
+    const mid = (lo + hi) >> 1;
+    if (ranges[mid][1] <= first) lo = mid + 1;
+    else hi = mid;
+  }
+  const kept = Math.max(0, lo - 1);
+  const from = kept === 0 ? 0 : ranges[kept][0];
+
+  const blanks = new Uint8Array(n);
+  blanks.set(was.blanks.subarray(0, from));
+  const blocks: BlockNode[] = previous.blocks.slice(0, kept);
+  const raws = previous.raws.slice(0, kept);
+  const next: Array<[number, number]> = ranges.slice(0, kept);
+  const fresh: Array<[number, number]> = [];
+  const stop = parseBlocks(
     lines,
-    partial,
+    was.partial,
     blocks,
-    ranges,
-    options.isComponent ?? NO_COMPONENTS,
-    options.expressions === true,
+    fresh,
+    was.isComponent,
+    was.expressions,
+    {
+      from,
+      blanks,
+      resync: (i) => i >= suffix && was.blanks[i - shift] === 1,
+    },
   );
-  return {
-    blocks,
-    raws: ranges.map(([a, b]) => lines.slice(a, b).join('\n')),
-  };
+  for (const [a, b] of fresh) {
+    raws.push(lines.slice(a, b).join('\n'));
+    next.push([a, b]);
+  }
+  if (stop < n) {
+    // the previous parse from the same place over the same lines: its
+    // blocks, where they now are
+    const at = stop - shift;
+    blanks.set(was.blanks.subarray(at), stop);
+    let j = ranges.length;
+    while (j > 0 && ranges[j - 1][0] >= at) j -= 1;
+    for (; j < ranges.length; j += 1) {
+      blocks.push(previous.blocks[j]);
+      raws.push(previous.raws[j]);
+      next.push([ranges[j][0] + shift, ranges[j][1] + shift]);
+    }
+  }
+  return remember({ blocks, raws }, { ...was, lines, ranges: next, blanks });
 }
 
 // --- block layer -----------------------------------------------------------
 
+/** The top-level call's extra: where to start, where to record the blank
+ *  lines it stands on, and when to stop (`resume`). */
+interface TopLevel {
+  from: number;
+  blanks: Uint8Array;
+  resync?: (line: number) => boolean;
+}
+
 /**
  * Parse a run of lines into blocks. `tailOpen` says the end of `lines` is
  * the live end of a streaming document — the license for every "complete it
  * anyway" rule. `ranges`, when given, receives each block's [start, endExcl)
  * line range (only the top-level call wants them, for the streaming cache).
+ * Returns the line it stopped at: the end, or where `top.resync` said the
+ * rest would come out as it did before.
  */
 function parseBlocks(
   lines: string[],
@@ -214,8 +351,9 @@ function parseBlocks(
   ranges?: Array<[number, number]>,
   isComponent: (name: string) => boolean = NO_COMPONENTS,
   expressions = false,
-): void {
-  let i = 0;
+  top?: TopLevel,
+): number {
+  let i = top?.from ?? 0;
   const n = lines.length;
 
   let paraStart = -1;
@@ -245,6 +383,10 @@ function parseBlocks(
 
     if (RE_BLANK.test(line)) {
       flushPara(i);
+      if (top) {
+        if (top.resync?.(i)) return i;
+        top.blanks[i] = 1;
+      }
       i += 1;
       continue;
     }
@@ -571,6 +713,7 @@ function parseBlocks(
   }
 
   flushPara(n);
+  return n;
 }
 
 // --- lists -----------------------------------------------------------------

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/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;