@react-x11/components 0.9.0 → 0.10.0

package/src/maps/gl/cover.ts

@@ -18,7 +18,14 @@
 // projection — markers, overlays, labels, `project()`. `tileCover` reads a
 // smaller tile one level deeper instead, which puts every image at its own
 // natural size on the one world everything shares.
-import { DEFAULT_TILE_SIZE, tileCover, transformFor } from '../proj.js';
+import {
+  BELOW,
+  DEFAULT_TILE_SIZE,
+  FILL_DEPTH,
+  fillFromBelow,
+  tileCover,
+  transformFor,
+} from '../proj.js';
 import type { MapCamera, TileId, TilePyramid } from '../proj.js';
 import type { GlTileData } from './buckets.js';
 import type { RenderTile } from './renderer.js';
@@ -27,6 +34,17 @@ import type { RenderTile } from './renderer.js';
  *  source has no data there, `undefined` while it is still to come. */
 export interface TileLookup {
   get(tile: TileId): GlTileData | null | undefined;
+  /**
+   * What the store has answered for at or under a tile: `'here'` for the
+   * tile itself, `'below'` for only tiles under it — within `FILL_DEPTH`
+   * levels — and `undefined` for neither.
+   *
+   * What lets a hole's search for pieces skip the parts of the pyramid that
+   * hold nothing. Without it the search asks `get` for every tile down to
+   * that depth — which costs lookups, and stamps a tile still loading as
+   * used, so a load the view has left is not cancelled.
+   */
+  holds?(tile: TileId): 'here' | 'below' | undefined;
 }
 
 export interface CoverResult {
@@ -53,10 +71,18 @@ const MAX_ANCESTOR = 8;
  * The frame's tiles, centre-out, each with its screen square and its clip.
  *
  * A hole — a tile still loading, or one the source has no data for — is
- * covered from whichever side has geometry: the nearest ancestor, drawn at
- * its own larger size and clipped to the hole; or, zooming out, the four
- * children, when all of them are in hand. `AGENTS.md`'s rule for the
- * retained cache holds here too: a pyramid has two neighbours.
+ * covered from whichever side has geometry. Zooming out, that is the tiles
+ * under it: each quarter from the nearest level that has it, down to
+ * `FILL_DEPTH`. Whatever they leave, and the whole of a hole with nothing
+ * under it, is the nearest ancestor's, drawn at its own larger size and
+ * clipped to each gap. `AGENTS.md`'s rule for the retained cache holds here
+ * too: a pyramid has two neighbours.
+ *
+ * The first cut tried the ancestor first, and the children only when all
+ * four of them were in hand. A zoom out leaves the level it came from in
+ * the middle of the view, covering only part of the tiles at the edges, and
+ * a quick one leaves it two or three levels down: both were the background,
+ * with the sharper tiles in hand.
  */
 export function renderCover(
   camera: MapCamera,
@@ -118,53 +144,62 @@ export function renderCover(
       own++;
       continue;
     }
-    // An ancestor: the same ground, `2^k` times the size, from `sub` cells
-    // above and to the left of this entry's square.
-    let found = false;
+    // Under it: a tile with no data has nothing under it either, and past
+    // the pyramid's depth there is nothing to find.
     const { z, x, y } = entry.tile;
+    const below = fillFromBelow(
+      entry.tile,
+      data === null ? 0 : Math.min(FILL_DEPTH, pyramid.maxZoom - z),
+      (under) => {
+        const held = lookup.holds ? lookup.holds(under) : 'here';
+        if (held === undefined) return undefined;
+        if (held === 'below') return BELOW;
+        const got = lookup.get(under);
+        return got === undefined ? BELOW : got;
+      },
+    );
+    for (const piece of below.pieces) {
+      const size = clip.width / piece.span;
+      const px = clip.x + piece.x * size;
+      const py = clip.y + piece.y * size;
+      tiles.push({
+        data: piece.value,
+        x: px,
+        y: py,
+        size,
+        clip: { x: px, y: py, width: size, height: size },
+      });
+    }
+    if (below.covered) descendants++;
+    if (below.gaps.length === 0) continue;
+    // Over it: an ancestor, the same ground `2^k` times the size, from
+    // `sub` cells above and to the left of this entry's square — drawn once
+    // for each gap, clipped to it.
     for (let k = 1; k <= MAX_ANCESTOR && z - k >= pyramid.minZoom; k++) {
       const ancestor = { z: z - k, x: x >> k, y: y >> k };
       const stand = lookup.get(ancestor);
       if (!stand) continue;
-      const span = 1 << k;
-      const size = clip.width * span;
-      tiles.push({
-        data: stand,
-        x: clip.x - (x - (ancestor.x << k)) * clip.width,
-        y: clip.y - (y - (ancestor.y << k)) * clip.width,
-        size,
-        clip,
-      });
+      const size = clip.width * (1 << k);
+      const sx = clip.x - (x - (ancestor.x << k)) * clip.width;
+      const sy = clip.y - (y - (ancestor.y << k)) * clip.width;
+      for (const gap of below.gaps) {
+        const edge = clip.width / gap.span;
+        tiles.push({
+          data: stand,
+          x: sx,
+          y: sy,
+          size,
+          clip: {
+            x: clip.x + gap.x * edge,
+            y: clip.y + gap.y * edge,
+            width: edge,
+            height: edge,
+          },
+        });
+      }
       ancestors++;
-      found = true;
       break;
     }
-    if (found || data === null || z + 1 > pyramid.maxZoom) continue;
-    // Zooming out: the finer level is what is in hand. Only when all four
-    // children have answered, or the hole would be patched with holes.
-    const children: (GlTileData | null)[] = [];
-    for (let dy = 0; dy < 2; dy++) {
-      for (let dx = 0; dx < 2; dx++) {
-        const child = lookup.get({ z: z + 1, x: x * 2 + dx, y: y * 2 + dy });
-        if (child === undefined) break;
-        children.push(child);
-      }
-    }
-    if (children.length !== 4) continue;
-    const half = clip.width / 2;
-    children.forEach((child, i) => {
-      if (!child) return;
-      const cx = clip.x + (i % 2) * half;
-      const cy = clip.y + Math.floor(i / 2) * half;
-      tiles.push({
-        data: child,
-        x: cx,
-        y: cy,
-        size: half,
-        clip: { x: cx, y: cy, width: half, height: half },
-      });
-    });
-    descendants++;
   }
   return { tiles, missing, level, own, ancestors, descendants, inView };
 }

package/src/maps/gl/placement.ts

@@ -17,7 +17,7 @@
 //    fits its street at this zoom, it would be cut by the edge, or something
 //    that outranks it arrives.
 //  - **Labels fade**, in and out, over {@link FADE_MS}. A label never pops;
-//    one whose raster is still being set waits, invisibly, and fades in
+//    one whose field is still being set waits, invisibly, and fades in
 //    when it lands.
 //  - **Labels do not slide.** Anchors are fixed ground, so a label moves
 //    exactly with the map; when a street's label leaves the view another
@@ -42,8 +42,16 @@ import {
   estimateWidth,
 } from '../anchors.js';
 import type { GlLabelData } from '../anchors.js';
-import { haloReach } from './text.js';
+import { fieldReach } from './text.js';
 import type { AtlasEntry, LabelAtlas } from './text.js';
+import {
+  DEFAULT_ICON_COLOR,
+  DEFAULT_ICON_GLYPH_COLOR,
+  DEFAULT_ICON_SIZE,
+  ICON_GAP,
+  isMapIcon,
+} from '../icons.js';
+import type { MapIcon } from '../icons.js';
 
 /** A rectangle in device pixels. */
 interface Rect {
@@ -85,23 +93,25 @@ export interface PlacementFrame {
    *  must, and what the zoom uncovers is named once it stops — not labels
    *  arriving and leaving at every step of it. `true` by default. */
   admit?: boolean;
-  /** The camera is moving: a label keeps the raster it has, rather than
-   *  asking for one at each size its zoom ramp passes through. */
-  moving?: boolean;
 }
 
 /** Floats per label instance; the layout `renderer.ts` binds. */
-export const LABEL_INSTANCE = 18;
+export const LABEL_INSTANCE = 19;
 
 /** The frame's labels, ready to draw. */
 export interface LabelBatch {
   atlas: LabelAtlas;
   /** {@link LABEL_INSTANCE} floats per label: centre x, y (device
-   *  pixels); cos, sin of the baseline; the atlas rect x, y, w, h; ink
-   *  and halo colour, premultiplied and faded; halo radius; `1` to set
-   *  the label on whole pixels. */
+   *  pixels); cos, sin of the baseline; the field's rect in the atlas x,
+   *  y, w, h (texels); ink and halo colour, premultiplied and faded; halo
+   *  radius (device pixels); `1` to set the label on whole pixels; and
+   *  device pixels per field texel — the drawn size over the atlas's
+   *  base. */
   instances: Float32Array;
   count: number;
+  /** Labels drawn: fewer than `count` where an icon is two instances of
+   *  its own beside its name's. `count` where absent. */
+  labels?: number;
 }
 
 export interface PlacementStats {
@@ -130,12 +140,23 @@ const CELL = 64;
 interface LayerLabels {
   id: string;
   rank: number;
-  /** Device pixels, whole — the raster's size. */
+  /** Device pixels — not rounded: one field draws any size. */
   size: number;
   repeat: number;
   ink: Rgba;
   halo: Rgba | null;
   haloPx: number;
+  icon: LayerIcon | null;
+}
+
+/** A layer's icon at a zoom: device pixels across, the gap to the name,
+ *  and its two colours. */
+interface LayerIcon {
+  name: MapIcon;
+  size: number;
+  gap: number;
+  plate: Rgba;
+  glyph: Rgba;
 }
 
 /** A label on screen, or fading. Its ground is mercator, so it outlives
@@ -158,8 +179,6 @@ interface Shown {
   priority: number;
   opacity: number;
   placed: boolean;
-  /** The size it has a raster at — drawn until the current size's lands. */
-  drawn: number;
 }
 
 interface Candidate {
@@ -172,6 +191,9 @@ interface Candidate {
   point: boolean;
   sx: number;
   sy: number;
+  /** How far right of `sx` its box's centre is: an icon's name is set
+   *  beside it. Device pixels; set once the box is measured. */
+  ox: number;
   angle: number;
   cos: number;
   sin: number;
@@ -226,7 +248,7 @@ export class LabelPlacer {
 
   /**
    * Choose the frame's labels. Asks `atlas` for each contender's box, as
-   * the frame's budget allows, and for each winner's raster.
+   * the frame's budget allows, and for each winner's field.
    */
   place(frame: PlacementFrame, atlas: LabelAtlas): void {
     const started = now();
@@ -372,18 +394,28 @@ export class LabelPlacer {
       }
       const box = atlas.measure(c.text, c.size);
       if (!box || box.width === 0) continue;
-      const w = box.width;
-      const h = box.height;
+      let w = box.width;
+      let h = box.height;
       if (!c.point) {
         const need = w / 2 + h * LINE_MARGIN;
         if (c.avail < (c.shown ? need * 0.9 : need)) continue;
       }
+      // An icon on the point and the name beside it are one box, placed
+      // and given way as one.
+      const icon = this._icon(layers[c.layer], c.point, atlas);
+      if (icon) {
+        const full = icon.size + icon.gap + w;
+        c.ox = (full - icon.size) / 2;
+        w = full;
+        h = Math.max(h, icon.size);
+      }
+      const bx = c.sx + c.ox;
       const hw = (Math.abs(c.cos) * w + Math.abs(c.sin) * h) / 2;
       const hh = (Math.abs(c.sin) * w + Math.abs(c.cos) * h) / 2;
       if (
-        c.sx - hw < inset ||
+        bx - hw < inset ||
         c.sy - hh < inset ||
-        c.sx + hw > width - inset ||
+        bx + hw > width - inset ||
         c.sy + hh > height - inset
       ) {
         continue;
@@ -425,7 +457,6 @@ export class LabelPlacer {
               size: c.size,
               opacity: 0,
               placed: false,
-              drawn: 0,
             } as Shown);
           fresh.mx = c.mx;
           fresh.my = c.my;
@@ -442,8 +473,12 @@ export class LabelPlacer {
       }
       shown.placed = true;
       shown.size = c.size;
-      if (!frame.moving || shown.drawn === 0)
-        atlas.entry(shown.text, shown.size);
+      atlas.entry(shown.text);
+      const icon = this._icon(layers[shown.layer], shown.point, atlas);
+      if (icon) {
+        atlas.icon(icon.name, 'plate');
+        atlas.icon(icon.name, 'glyph');
+      }
     }
 
     this.stats = {
@@ -464,24 +499,27 @@ export class LabelPlacer {
     this._last = frame.now;
     const step = dt / FADE_MS;
     const layers = this._layersAt(frame.style, frame.zoom, frame.scale);
-    const reach = haloReach(atlas.pad);
+    // How far past its glyphs a field sees, in its own texels: the widest
+    // halo it can draw, times the label's scale.
+    const reach = fieldReach(atlas.pad);
     const halfW = frame.width / 2;
     const halfH = frame.height / 2;
     let count = 0;
+    let labels = 0;
     for (const shown of [...this._shown]) {
       const layer = layers[shown.layer];
-      let entry: AtlasEntry | null;
-      if (frame.moving && shown.drawn > 0 && shown.drawn !== shown.size) {
-        // Its zoom ramp has moved on; the size it has serves until the
-        // view is still.
-        entry = atlas.entry(shown.text, shown.drawn);
-      } else {
-        entry = atlas.entry(shown.text, shown.size);
-        if (entry) shown.drawn = shown.size;
-        else if (shown.drawn > 0) entry = atlas.entry(shown.text, shown.drawn);
-      }
+      // One field for every size: a zoom ramp that grows the type draws the
+      // same raster larger, the frame it changes.
+      const entry = atlas.entry(shown.text);
+      // A name set beside an icon waits for the icon as well: the name
+      // alone is what the icon is there to explain.
+      const icon = this._icon(layer, shown.point, atlas);
+      const plate = icon ? atlas.icon(icon.name, 'plate') : null;
+      const glyph = icon ? atlas.icon(icon.name, 'glyph') : null;
+      const ready =
+        entry !== null && (!icon || (plate !== null && glyph !== null));
       // Nothing to show yet: wait at zero rather than fade in unseen.
-      if (entry && layer) {
+      if (ready && layer) {
         shown.opacity = shown.placed
           ? Math.min(1, shown.opacity + step)
           : Math.max(0, shown.opacity - step);
@@ -492,44 +530,111 @@ export class LabelPlacer {
         this._shown.delete(shown);
         continue;
       }
-      if (!entry || !layer || shown.opacity <= 0) continue;
+      if (!ready || !entry || !layer || shown.opacity <= 0) continue;
       let dx = shown.mx - frame.centerX;
       dx -= Math.round(dx);
       const sx = halfW + dx * frame.world;
       const sy = halfH + (shown.my - frame.centerY) * frame.world;
       const eased = shown.opacity * shown.opacity * (3 - 2 * shown.opacity);
-      if (this._instances.length < (count + 1) * LABEL_INSTANCE) {
-        const grown = new Float32Array(this._instances.length * 2);
-        grown.set(this._instances);
-        this._instances = grown;
-      }
-      const d = this._instances;
-      const at = count * LABEL_INSTANCE;
-      const level = shown.angle === 0;
-      d[at] = sx;
-      d[at + 1] = sy;
-      d[at + 2] = level ? 1 : Math.cos(shown.angle);
-      d[at + 3] = level ? 0 : Math.sin(shown.angle);
-      d[at + 4] = entry.x;
-      d[at + 5] = entry.y;
-      d[at + 6] = entry.width;
-      d[at + 7] = entry.height;
       const ink = premultiplied(layer.ink, eased);
-      d[at + 8] = ink[0];
-      d[at + 9] = ink[1];
-      d[at + 10] = ink[2];
-      d[at + 11] = ink[3];
       const halo = layer.halo ? premultiplied(layer.halo, eased) : ZERO;
-      d[at + 12] = halo[0];
-      d[at + 13] = halo[1];
-      d[at + 14] = halo[2];
-      d[at + 15] = halo[3];
-      d[at + 16] = layer.halo ? Math.min(layer.haloPx, reach) : 0;
-      d[at + 17] = level ? 1 : 0;
-      count++;
+      const k = shown.size / atlas.base;
+      const haloPx = layer.halo ? Math.min(layer.haloPx, reach * k) : 0;
+      if (icon && plate && glyph) {
+        // The plate under its halo, the glyph on it, and the name level
+        // beside it: the string is its field less the margin, and its
+        // left edge goes the gap past the plate's right.
+        const ki = icon.size / atlas.base;
+        const plateHalo = layer.halo ? Math.min(layer.haloPx, reach * ki) : 0;
+        count = this._put(
+          count,
+          sx,
+          sy,
+          0,
+          plate,
+          premultiplied(icon.plate, eased),
+          halo,
+          plateHalo,
+          ki,
+        );
+        count = this._put(
+          count,
+          sx,
+          sy,
+          0,
+          glyph,
+          premultiplied(icon.glyph, eased),
+          ZERO,
+          0,
+          ki,
+        );
+        const tx =
+          sx +
+          icon.size / 2 +
+          icon.gap +
+          ((entry.width - 2 * atlas.pad) * k) / 2;
+        count = this._put(count, tx, sy, 0, entry, ink, halo, haloPx, k);
+      } else {
+        count = this._put(
+          count,
+          sx,
+          sy,
+          shown.angle,
+          entry,
+          ink,
+          halo,
+          haloPx,
+          k,
+        );
+      }
+      labels++;
     }
-    this.stats.drawn = count;
-    return { atlas, instances: this._instances, count };
+    this.stats.drawn = labels;
+    return { atlas, instances: this._instances, count, labels };
+  }
+
+  /** One instance — a label's string, or a piece of its icon — written at
+   *  `count`: answers the count after it. Level (`angle` 0) is set on
+   *  whole pixels. */
+  private _put(
+    count: number,
+    x: number,
+    y: number,
+    angle: number,
+    entry: AtlasEntry,
+    ink: Rgba,
+    halo: Rgba,
+    haloPx: number,
+    scale: number,
+  ): number {
+    if (this._instances.length < (count + 1) * LABEL_INSTANCE) {
+      const grown = new Float32Array(this._instances.length * 2);
+      grown.set(this._instances);
+      this._instances = grown;
+    }
+    const d = this._instances;
+    const at = count * LABEL_INSTANCE;
+    const level = angle === 0;
+    d[at] = x;
+    d[at + 1] = y;
+    d[at + 2] = level ? 1 : Math.cos(angle);
+    d[at + 3] = level ? 0 : Math.sin(angle);
+    d[at + 4] = entry.x;
+    d[at + 5] = entry.y;
+    d[at + 6] = entry.width;
+    d[at + 7] = entry.height;
+    d[at + 8] = ink[0];
+    d[at + 9] = ink[1];
+    d[at + 10] = ink[2];
+    d[at + 11] = ink[3];
+    d[at + 12] = halo[0];
+    d[at + 13] = halo[1];
+    d[at + 14] = halo[2];
+    d[at + 15] = halo[3];
+    d[at + 16] = haloPx;
+    d[at + 17] = level ? 1 : 0;
+    d[at + 18] = scale;
+    return count + 1;
   }
 
   // --- internals -------------------------------------------------------------
@@ -587,6 +692,7 @@ export class LabelPlacer {
       point,
       sx,
       sy,
+      ox: 0,
       angle: a,
       cos: Math.cos(a),
       sin: Math.sin(a),
@@ -607,6 +713,18 @@ export class LabelPlacer {
     };
   }
 
+  /** The icon a label of `layer` is set with: none for a name along a
+   *  street, and none where the atlas cannot draw it — the name is then set
+   *  alone rather than not at all. */
+  private _icon(
+    layer: LayerLabels | null | undefined,
+    point: boolean,
+    atlas: LabelAtlas,
+  ): LayerIcon | null {
+    const icon = point ? (layer?.icon ?? null) : null;
+    return icon && !atlas.iconFailed(icon.name) ? icon : null;
+  }
+
   /** Each symbol layer's labelling at this zoom, by layer index — null
    *  where it does not label. */
   private _layersAt(
@@ -630,13 +748,13 @@ export class LabelPlacer {
         symbol.textHaloWidth === undefined
           ? 1
           : resolveZoomed(symbol.textHaloWidth, zoom);
+      // Not rounded: a field draws any size, so a ramp grows the type
+      // continuously rather than a whole pixel at a time.
       const size = Math.max(
         1,
-        Math.round(
-          (symbol.textSize === undefined
-            ? 12
-            : resolveZoomed(symbol.textSize, zoom)) * scale,
-        ),
+        (symbol.textSize === undefined
+          ? 12
+          : resolveZoomed(symbol.textSize, zoom)) * scale,
       );
       return {
         id: layer.id,
@@ -646,10 +764,43 @@ export class LabelPlacer {
         ink,
         halo: halo && haloWidth > 0 ? halo : null,
         haloPx: haloWidth * scale,
+        icon: this._iconOf(symbol, zoom, scale),
       };
     });
   }
 
+  /** A layer's icon at this zoom, or null where it sets none — or names
+   *  one this version does not draw, or a colour that does not parse. */
+  private _iconOf(
+    symbol: SymbolLayer,
+    zoom: number,
+    scale: number,
+  ): LayerIcon | null {
+    if (!isMapIcon(symbol.icon)) return null;
+    const plate = this._color(
+      symbol.iconColor
+        ? resolveZoomed(symbol.iconColor, zoom)
+        : DEFAULT_ICON_COLOR,
+    );
+    const glyph = this._color(
+      symbol.iconGlyphColor
+        ? resolveZoomed(symbol.iconGlyphColor, zoom)
+        : DEFAULT_ICON_GLYPH_COLOR,
+    );
+    if (!plate || !glyph) return null;
+    const size =
+      symbol.iconSize === undefined
+        ? DEFAULT_ICON_SIZE
+        : resolveZoomed(symbol.iconSize, zoom);
+    return {
+      name: symbol.icon,
+      size: Math.max(1, Math.round(size * scale)),
+      gap: ICON_GAP * scale,
+      plate,
+      glyph,
+    };
+  }
+
   private _color(value: string): Rgba | null {
     let color = this._colors.get(value);
     if (color === undefined) {
@@ -743,11 +894,12 @@ class CollisionGrid {
     const out = this._scratch;
     out.length = 0;
     if (c.angle === 0) {
+      const x = c.sx + c.ox;
       out.push(
         0,
-        c.sx - w / 2 - pad,
+        x - w / 2 - pad,
         c.sy - h / 2 - pad,
-        c.sx + w / 2 + pad,
+        x + w / 2 + pad,
         c.sy + h / 2 + pad,
       );
       return out;