@react-x11/components 0.9.0 → 0.10.0

package/src/maps/anchors.ts

@@ -36,8 +36,10 @@
 // Everything leaves as one Float32Array and a string table, so a worker can
 // hand it over with the buckets (see `./gl/store.ts`).
 import { GeomType, GeometryBuffer } from './mvt.js';
-import type { FeatureCursor, VectorTile } from './mvt.js';
+import type { FeatureCursor, VectorTile, VectorTileLayer } from './mvt.js';
 import type { PreparedStyle } from './paint.js';
+import { latFromMercatorY } from './proj.js';
+import type { TileId } from './proj.js';
 import type { SymbolLayer } from './style.js';
 
 // --- the fit rules both renderers place by ------------------------------------
@@ -241,6 +243,10 @@ export function buildTileLabels(
   tile: VectorTile,
   prepared: PreparedStyle,
   extent: number,
+  /** Which tile: what turns a `snapInto` distance in metres into tile
+   *  units. Without it no distance can be known, and only a point already
+   *  inside a polygon moves. */
+  id?: TileId,
 ): GlLabelData {
   const started = now();
   const texts: string[] = [];
@@ -259,6 +265,11 @@ export function buildTileLabels(
     const groups = new Map<number, LineGroup>();
     // Which name first touched each vertex, or -1 once a second did.
     const touched = new Map<number, number>();
+    // A layer that snaps into polygons collects its points first — x, y,
+    // text, priority — since which point a polygon belongs to depends on
+    // every other point that could claim it.
+    const snap = symbol.snapInto;
+    const snaps: number[] | null = snap ? [] : null;
 
     for (let f = 0; f < source.length; f++) {
       source.seek(f, cursor);
@@ -309,10 +320,23 @@ export function buildTileLabels(
       if (!anchor) continue;
       const x = anchor.x * k;
       const y = anchor.y * k;
+      if (snaps && cursor.type === GeomType.Point) {
+        // The buffer's points too, and judged before the tile's square:
+        // a polygon near the edge is claimed by points on either side of
+        // it, and both tiles that hold it must see the same claims.
+        snaps.push(x, y, t, priority);
+        continue;
+      }
       if (x < 0 || y < 0 || x >= extent || y >= extent) continue;
       out.point(x, y, t, i, priority);
     }
 
+    if (snap && snaps) {
+      const polygons = tile.layers.get(snap.sourceLayer);
+      const within = (snap.within ?? SNAP_WITHIN) / metresPerUnit(id, extent);
+      snapPoints(polygons, within, snaps, extent, i, out, buffer);
+    }
+
     for (const group of groups.values()) {
       for (const chain of mergeParts(group.parts)) {
         anchorChain(chain, touched, extent, group, i, out);
@@ -323,6 +347,288 @@ export function buildTileLabels(
   return { texts, anchors: out.take(), count: out.count, ms: now() - started };
 }
 
+/** How far a point is taken to belong to a polygon it is outside, metres,
+ *  where the layer does not say. An address point in the lot sits a few
+ *  metres off its house; much past this, the nearest building is as often
+ *  a neighbour's — the house the number is for not being mapped at all. */
+const SNAP_WITHIN = 15;
+/** The earth's circumference at the equator, metres (Web Mercator's). */
+const EQUATOR = 40075016.686;
+
+/** Metres on the ground per tile unit, at the tile's middle row. */
+function metresPerUnit(id: TileId | undefined, extent: number): number {
+  const n = 2 ** (id?.z ?? 0);
+  const lat = id ? latFromMercatorY((id.y + 0.5) / n) : 0;
+  return (EQUATOR * Math.cos((lat * Math.PI) / 180)) / (n * extent);
+}
+
+/** One polygon's outer ring, in tile units: its points, its box, and the
+ *  point inside it a label moved into it is set on. */
+interface SnapRing {
+  points: number[];
+  x0: number;
+  y0: number;
+  x1: number;
+  y1: number;
+  cx: number;
+  cy: number;
+}
+
+/** The grid rings are found by, in tile units: a z14 tile is 16 cells a
+ *  side, a few dozen buildings each. */
+const SNAP_CELL = 256;
+const snapCell = (gx: number, gy: number): number =>
+  (gx + 1024) * 4096 + (gy + 1024);
+
+/**
+ * Point labels moved into the polygon each one belongs to — a house number
+ * into its house.
+ *
+ * A point inside a polygon belongs to it; one outside, to the nearest
+ * polygon whose outline is within `within` tile units. It moves only if it
+ * is the **one** point its polygon is claimed by: a duplex's two numbers, or
+ * a garage nearer the street than the house, would otherwise pile several
+ * numbers onto one roof — and collision would then keep one of them, on a
+ * building that is not only its own. Every point that does not move stays
+ * exactly where the data put it.
+ *
+ * `points` are the whole tile's, buffer included, so a polygon near the edge
+ * is claimed alike in both tiles that hold it; each point is then anchored
+ * only in the tile its own position is in, as every other point is. One
+ * whose polygon's middle is in the next tile over stays put rather than
+ * move out of the tile that offers it.
+ */
+function snapPoints(
+  polygons: VectorTileLayer | undefined,
+  within: number,
+  points: readonly number[],
+  extent: number,
+  layer: number,
+  out: AnchorWriter,
+  buffer: GeometryBuffer,
+): void {
+  const count = points.length / 4;
+  const target = new Int32Array(count).fill(-1);
+  const rings = polygons ? snapRings(polygons, extent, buffer) : [];
+  if (rings.length > 0) {
+    const grid = new Map<number, number[]>();
+    rings.forEach((ring, r) => {
+      for (let gx = cellOf(ring.x0); gx <= cellOf(ring.x1); gx++) {
+        for (let gy = cellOf(ring.y0); gy <= cellOf(ring.y1); gy++) {
+          const key = snapCell(gx, gy);
+          const list = grid.get(key);
+          if (list) list.push(r);
+          else grid.set(key, [r]);
+        }
+      }
+    });
+    const claims = new Int32Array(rings.length);
+    // Which query last looked at each ring: a ring spanning several cells
+    // is one candidate, not several.
+    const seen = new Int32Array(rings.length).fill(-1);
+    for (let p = 0; p < count; p++) {
+      const r = ownerOf(
+        rings,
+        grid,
+        seen,
+        p,
+        points[p * 4],
+        points[p * 4 + 1],
+        within,
+      );
+      if (r >= 0) {
+        target[p] = r;
+        claims[r]++;
+      }
+    }
+    for (let p = 0; p < count; p++) {
+      if (target[p] >= 0 && claims[target[p]] !== 1) target[p] = -1;
+    }
+  }
+  for (let p = 0; p < count; p++) {
+    let x = points[p * 4];
+    let y = points[p * 4 + 1];
+    if (x < 0 || y < 0 || x >= extent || y >= extent) continue;
+    const r = target[p];
+    if (r >= 0) {
+      const ring = rings[r];
+      if (
+        ring.cx >= 0 &&
+        ring.cy >= 0 &&
+        ring.cx < extent &&
+        ring.cy < extent
+      ) {
+        x = ring.cx;
+        y = ring.cy;
+      }
+    }
+    out.point(x, y, points[p * 4 + 2], layer, points[p * 4 + 3]);
+  }
+}
+
+const cellOf = (v: number): number => Math.floor(v / SNAP_CELL);
+
+/** Every polygon's outer rings, in tile units. Holes are not a building's
+ *  own ground, and a courtyard is not where a number goes. */
+function snapRings(
+  source: VectorTileLayer,
+  extent: number,
+  buffer: GeometryBuffer,
+): SnapRing[] {
+  const k = extent / source.extent;
+  const cursor = source.feature(0);
+  const rings: SnapRing[] = [];
+  for (let f = 0; f < source.length; f++) {
+    source.seek(f, cursor);
+    if (cursor.type !== GeomType.Polygon) continue;
+    cursor.readGeometry(buffer);
+    for (let part = 0; part < buffer.parts; part++) {
+      if (buffer.areas[part] <= 0) continue;
+      const from = buffer.starts[part];
+      const to = buffer.starts[part + 1];
+      if (to - from < 3) continue;
+      const points: number[] = [];
+      let x0 = Infinity;
+      let y0 = Infinity;
+      let x1 = -Infinity;
+      let y1 = -Infinity;
+      for (let p = from; p < to; p++) {
+        const x = buffer.coords[p * 2] * k;
+        const y = buffer.coords[p * 2 + 1] * k;
+        points.push(x, y);
+        if (x < x0) x0 = x;
+        if (x > x1) x1 = x;
+        if (y < y0) y0 = y;
+        if (y > y1) y1 = y;
+      }
+      const [cx, cy] = interiorPoint(points, x0, y0, x1, y1);
+      rings.push({ points, x0, y0, x1, y1, cx, cy });
+    }
+  }
+  return rings;
+}
+
+/**
+ * A point inside a ring to set a label on: its centroid, which is inside
+ * for all but the most contorted outline — 99.8% of the building rings in
+ * the tiles this was measured on — and where it is not, the middle of the
+ * widest span of the ring along the centroid's row.
+ */
+function interiorPoint(
+  points: readonly number[],
+  x0: number,
+  y0: number,
+  x1: number,
+  y1: number,
+): [number, number] {
+  let area = 0;
+  let sx = 0;
+  let sy = 0;
+  const n = points.length;
+  for (let i = 0, j = n - 2; i < n; j = i, i += 2) {
+    const cross = points[j] * points[i + 1] - points[i] * points[j + 1];
+    area += cross;
+    sx += (points[j] + points[i]) * cross;
+    sy += (points[j + 1] + points[i + 1]) * cross;
+  }
+  if (area === 0) return [(x0 + x1) / 2, (y0 + y1) / 2];
+  const cx = sx / (3 * area);
+  const cy = sy / (3 * area);
+  if (insideRing(points, cx, cy)) return [cx, cy];
+  const crossings: number[] = [];
+  for (let i = 0, j = n - 2; i < n; j = i, i += 2) {
+    const ay = points[j + 1];
+    const by = points[i + 1];
+    if (ay > cy !== by > cy) {
+      crossings.push(
+        points[j] + ((cy - ay) / (by - ay)) * (points[i] - points[j]),
+      );
+    }
+  }
+  crossings.sort((a, b) => a - b);
+  let best = -1;
+  let mid = (x0 + x1) / 2;
+  for (let c = 0; c + 1 < crossings.length; c += 2) {
+    const span = crossings[c + 1] - crossings[c];
+    if (span > best) {
+      best = span;
+      mid = (crossings[c] + crossings[c + 1]) / 2;
+    }
+  }
+  return [mid, cy];
+}
+
+/** Even-odd: whether `x, y` is inside the ring. */
+function insideRing(points: readonly number[], x: number, y: number): boolean {
+  let inside = false;
+  const n = points.length;
+  for (let i = 0, j = n - 2; i < n; j = i, i += 2) {
+    const xi = points[i];
+    const yi = points[i + 1];
+    const xj = points[j];
+    const yj = points[j + 1];
+    if (yi > y !== yj > y && x < ((xj - xi) * (y - yi)) / (yj - yi) + xi) {
+      inside = !inside;
+    }
+  }
+  return inside;
+}
+
+/** How far `x, y` is from the ring's outline. */
+function distanceToRing(points: readonly number[], x: number, y: number) {
+  let best = Infinity;
+  const n = points.length;
+  for (let i = 0, j = n - 2; i < n; j = i, i += 2) {
+    const ax = points[j];
+    const ay = points[j + 1];
+    const dx = points[i] - ax;
+    const dy = points[i + 1] - ay;
+    const length = dx * dx + dy * dy;
+    const t =
+      length > 0
+        ? Math.max(0, Math.min(1, ((x - ax) * dx + (y - ay) * dy) / length))
+        : 0;
+    const d = Math.hypot(x - ax - t * dx, y - ay - t * dy);
+    if (d < best) best = d;
+  }
+  return best;
+}
+
+/** The ring a point belongs to — the one it is inside, else the nearest
+ *  within `within` — or -1. */
+function ownerOf(
+  rings: readonly SnapRing[],
+  grid: Map<number, number[]>,
+  seen: Int32Array,
+  query: number,
+  x: number,
+  y: number,
+  within: number,
+): number {
+  let best = -1;
+  let bestDistance = within;
+  for (let gx = cellOf(x - within); gx <= cellOf(x + within); gx++) {
+    for (let gy = cellOf(y - within); gy <= cellOf(y + within); gy++) {
+      for (const r of grid.get(snapCell(gx, gy)) ?? []) {
+        if (seen[r] === query) continue;
+        seen[r] = query;
+        const ring = rings[r];
+        // Past the box by more than the distance allowed: not a candidate.
+        const bx = Math.max(ring.x0 - x, 0, x - ring.x1);
+        const by = Math.max(ring.y0 - y, 0, y - ring.y1);
+        if (bx > bestDistance || by > bestDistance) continue;
+        if (bx === 0 && by === 0 && insideRing(ring.points, x, y)) return r;
+        const d = distanceToRing(ring.points, x, y);
+        if (d <= bestDistance) {
+          best = r;
+          bestDistance = d;
+        }
+      }
+    }
+  }
+  return best;
+}
+
 /**
  * Where a point-like feature's label goes: the point, or for a polygon the
  * middle of its largest ring's box — a cheap stand-in for the pole of

package/src/maps/controller.ts

@@ -240,18 +240,6 @@ const timers = globalThis as {
   performance?: { now(): number };
 };
 
-/**
- * The clock a glide is measured on.
- *
- * `performance.now()` rather than the `Date.now()` the settle window uses:
- * this one is compared across two frames of a 60Hz display, and `Date.now()`
- * counts whole milliseconds, so a sixth of the step would be error. Reached
- * through `globalThis` because `src/` compiles with `types: []`.
- */
-function now(): number {
-  return timers.performance?.now() ?? Date.now();
-}
-
 /**
  * The settle timer, unref'd where the runtime allows it.
  *
@@ -266,6 +254,29 @@ function arm(tick: () => void, ms: number): unknown {
   return handle;
 }
 
+/**
+ * The clock a glide is measured on, and the timer that steps it.
+ *
+ * `performance.now()` rather than the `Date.now()` the settle window uses:
+ * this one is compared across two frames of a 60Hz display, and `Date.now()`
+ * counts whole milliseconds, so a sixth of the step would be error. Reached
+ * through `globalThis` because `src/` compiles with `types: []`.
+ *
+ * One object, exported from this module though not from the package, so a
+ * test can stand in for both and step a glide a frame at a time. The glide
+ * is wall-clock time on purpose, and a runner slow enough to spend the whole
+ * of one inside a single `await` finds it over before it can look.
+ */
+export const glideClock = {
+  now(): number {
+    return timers.performance?.now() ?? Date.now();
+  },
+  arm,
+  disarm(handle: unknown): void {
+    timers.clearTimeout?.(handle);
+  },
+};
+
 function clamp(value: number, low: number, high: number): number {
   return value < low ? low : value > high ? high : value;
 }
@@ -287,6 +298,10 @@ export class MapController {
    * claims nothing and starts no gesture.
    */
   painting = false;
+  /** A camera move made while `painting`, waiting for the frame to end —
+   *  `previous` is the camera the *first* such move started from, so the
+   *  view is told the whole delta however many were fused. */
+  private _paintMove: { previous: MapCamera } | null = null;
 
   private _props: MapControllerProps = {};
   /** The camera, when the application does not control it. */
@@ -361,7 +376,7 @@ export class MapController {
   dispose(): void {
     if (this._settleTimer !== null) timers.clearTimeout?.(this._settleTimer);
     this._settleTimer = null;
-    if (this._glideTimer !== null) timers.clearTimeout?.(this._glideTimer);
+    if (this._glideTimer !== null) glideClock.disarm(this._glideTimer);
     this._glideTimer = null;
     this._glide = null;
   }
@@ -443,11 +458,49 @@ export class MapController {
     const controlled = this._props.camera !== undefined;
     if (!controlled) this._camera = camera;
     this._props.onCameraChange?.(camera);
-    if (this.painting) return;
+    if (this.painting) {
+      // A camera set from **inside** a frame, which is how every camera
+      // animation is written: the map's own `onFrame` is the clock, and the
+      // GL view calls it while it is still painting. Re-entering the paint
+      // is not on, but returning here used to drop the move's *scheduling*
+      // as well as its redraw — so the animation had nothing to ask for the
+      // next frame with, and stopped until something unrelated re-rendered.
+      //
+      // In the maps-gl example that something was the status bar's
+      // half-second interval, and it showed as exactly that: frames every
+      // 11ms, then a 511ms hole with the next request arriving at +508 —
+      // nobody asking, rather than anyone being slow. Manual panning never
+      // hit it because an input event is not inside a paint.
+      //
+      // So the move is remembered, with the camera it started from, and
+      // finished when the frame ends.
+      this._paintMove ??= { previous };
+      return;
+    }
     this.touch();
     if (!controlled) this._view?.moved(previous, camera, blit);
   }
 
+  /**
+   * A frame finished: do whatever `apply` deferred because it was painting.
+   * Called from both painters (`gl/view.ts`, `node.ts`) wherever `painting`
+   * goes back to false.
+   *
+   * Never a blit. A blit needs the exact transform it is shifting from, and
+   * what is flushed here may be several moves fused into one; a full redraw
+   * of a frame that was going to be drawn anyway costs nothing next to
+   * getting that wrong.
+   */
+  paintEnded(): void {
+    const move = this._paintMove;
+    if (!move) return;
+    this._paintMove = null;
+    this.touch();
+    if (this._props.camera === undefined) {
+      this._view?.moved(move.previous, this.camera(), false);
+    }
+  }
+
   getCamera(): MapCamera {
     const camera = this.camera();
     return { center: { ...camera.center }, zoom: camera.zoom };
@@ -501,6 +554,17 @@ export class MapController {
       this._maxZoom(),
     );
     if (zoom === camera.zoom) return;
+    this.apply(this._zoomedAbout(camera, zoom, x, y), false);
+  }
+
+  /** `camera` at `zoom`, with the point at pane-local `x`, `y` where it
+   *  was: what {@link zoomAbout} moves to, and what a glide arrives at. */
+  private _zoomedAbout(
+    camera: MapCamera,
+    zoom: number,
+    x: number,
+    y: number,
+  ): MapCamera {
     const before = this.transform(camera);
     const anchor = unprojectPoint(before, x, y);
     const after = this.transform({ center: camera.center, zoom });
@@ -509,21 +573,42 @@ export class MapController {
     const moved = projectLngLat(after, anchor);
     const dx = (moved.x - x) / after.world;
     const dy = (moved.y - y) / after.world;
-    this.apply(
-      {
-        zoom,
-        center: unprojectPoint(
-          {
-            ...after,
-            centerX: after.centerX + dx,
-            centerY: after.centerY + dy,
-          },
-          after.paneX,
-          after.paneY,
-        ),
-      },
-      false,
+    return {
+      zoom,
+      center: unprojectPoint(
+        {
+          ...after,
+          centerX: after.centerX + dx,
+          centerY: after.centerY + dy,
+        },
+        after.paneX,
+        after.paneY,
+      ),
+    };
+  }
+
+  /**
+   * Where the camera is going, when that is known before it gets there: the
+   * end of a wheel's glide. Null while nothing is gliding — a touchpad's
+   * stream, a drag or an application's own animation go wherever the next
+   * event says, and the view has only the camera to go on.
+   *
+   * What a renderer does with it is get there first: the tiles and label
+   * rasters of the view the glide stops at are asked for while the frames
+   * of the glide are still being drawn, so the settle has them in hand.
+   */
+  destination(): MapCamera | null {
+    const glide = this._glide;
+    if (!glide || !glide.easing) return null;
+    const camera = this.camera();
+    if (glide.applied !== camera.zoom) return null;
+    const zoom = clamp(
+      quantizeZoom(glide.target),
+      this._minZoom(),
+      this._maxZoom(),
     );
+    if (zoom === camera.zoom) return null;
+    return this._zoomedAbout(camera, zoom, glide.x, glide.y);
   }
 
   /**
@@ -550,7 +635,7 @@ export class MapController {
     y: number,
     smooth: boolean,
   ): void {
-    const at = now();
+    const at = glideClock.now();
     const camera = this.camera();
     const glide = this._glide;
     // Where this delta counts from: the target the wheel has already asked
@@ -590,13 +675,13 @@ export class MapController {
       this._glideTimer = null;
       const glide = this._glide;
       if (glide?.easing !== true) return;
-      const at = now();
+      const at = glideClock.now();
       // `stepZoom` clears the record when the target is reached or the
       // camera refuses a step, and this re-arms only while one is left.
       this.stepZoom(at, at - glide.at);
       this._armGlide();
     };
-    this._glideTimer = arm(tick, GLIDE_TICK_MS);
+    this._glideTimer = glideClock.arm(tick, GLIDE_TICK_MS);
   }
 
   /**

package/src/maps/gl/buckets.ts

@@ -38,6 +38,7 @@ import { GeomType, GeometryBuffer } from '../mvt.js';
 import type { FeatureCursor, VectorTile } from '../mvt.js';
 import type { PreparedLayer, PreparedStyle } from '../paint.js';
 import type { MapStyleLayer } from '../style.js';
+import type { TileId } from '../proj.js';
 import { buildTileLabels } from '../anchors.js';
 import type { GlLabelData } from '../anchors.js';
 
@@ -324,6 +325,9 @@ interface Group {
 export function buildTileBuckets(
   tile: VectorTile,
   prepared: PreparedStyle,
+  /** Which tile — what a label layer's `snapInto` distance is measured
+   *  against (`../anchors.ts`). */
+  id?: TileId,
 ): GlTileData {
   const started = now();
   const line = new Stream(1024);
@@ -445,7 +449,7 @@ export function buildTileBuckets(
     fill: fill.take(),
     fillRecords: fill.count,
     draws,
-    labels: buildTileLabels(tile, prepared, TILE_EXTENT),
+    labels: buildTileLabels(tile, prepared, TILE_EXTENT, id),
     stats: {
       features,
       lineRecords: line.count,

package/src/maps/gl/build-worker.ts

@@ -12,6 +12,7 @@
 // specifier would make every build depend on Node's type declarations.
 import { prepareStyle } from '../paint.js';
 import type { PreparedStyle } from '../paint.js';
+import type { TileId } from '../proj.js';
 import { parseVectorTile } from '../sources.js';
 import type { MapStyleLayer } from '../style.js';
 import { buildTileBuckets } from './buckets.js';
@@ -19,7 +20,13 @@ import { buildTileBuckets } from './buckets.js';
 /** What the store sends. */
 export type BuildRequest =
   | { type: 'style'; id: number; layers: MapStyleLayer[] }
-  | { type: 'build'; job: number; style: number; bytes: Uint8Array };
+  | {
+      type: 'build';
+      job: number;
+      style: number;
+      bytes: Uint8Array;
+      tile: TileId;
+    };
 
 interface Port {
   on(event: 'message', listener: (message: unknown) => void): void;
@@ -45,7 +52,11 @@ parentPort?.on('message', (message) => {
   try {
     const prepared = styles.get(request.style);
     if (!prepared) throw new Error(`style ${request.style} was never sent`);
-    const data = buildTileBuckets(parseVectorTile(request.bytes), prepared);
+    const data = buildTileBuckets(
+      parseVectorTile(request.bytes),
+      prepared,
+      request.tile,
+    );
     const transfer = [data.line, data.fill];
     if (data.labels) transfer.push(data.labels.anchors.buffer as ArrayBuffer);
     parentPort.postMessage({ job: request.job, data }, transfer);