@react-x11/components 0.9.0 → 0.11.0

package/src/maps/node.ts

@@ -206,6 +206,26 @@ interface VisibleTile {
  */
 const RESTYLE_WAIT_MS = 1500;
 
+/**
+ * The clock {@link RESTYLE_WAIT_MS} is measured on: the raster budget's,
+ * read at the same moment, as a frame begins.
+ *
+ * One object, exported from this module though not from the package, so a
+ * test can stand in for it and move the bound's time on a step at a time,
+ * as `glideClock` in `./controller.ts` does for a glide. On the real clock a
+ * test finds the swap only once the step that made it is over, and on a
+ * loaded runner one step took long enough to put that two and a half
+ * seconds past the bound. It is not the budget's own `now`, because a test
+ * that held that one would hold the raster deadline with it: a frame would
+ * draw every tile to the end, and there would be no redraw left for the
+ * bound to cut short.
+ */
+export const restyleClock = {
+  now(): number {
+    return now();
+  },
+};
+
 /**
  * The previous style, held on screen while a restyle draws the new one.
  *
@@ -240,7 +260,8 @@ interface Outgoing {
   view: string;
   moved: boolean;
   /** Milliseconds the map has been free to draw since the switch, and when
-   *  the last frame that was began — `null` when the last frame was not. */
+   *  the last frame that was began on {@link restyleClock} — `null` when
+   *  the last frame was not. */
   waited: number;
   lastDrawn: number | null;
 }
@@ -734,6 +755,7 @@ export class MapViewNode extends Node {
     if (!this._visible() || !isMapCanvas(ctx)) return;
 
     const started = now();
+    const restyleAt = restyleClock.now();
     const scale = this._scale;
     this._frameClip = damage
       ? {
@@ -794,6 +816,7 @@ export class MapViewNode extends Node {
       : box;
     if (!clip) {
       this._controller.painting = false;
+      this._controller.paintEnded();
       this._frameClip = null;
       return;
     }
@@ -838,7 +861,7 @@ export class MapViewNode extends Node {
       pane,
       stats,
       budget,
-      started,
+      restyleAt,
       !damage || containsRect(damage, box),
       progressive,
     );
@@ -895,6 +918,7 @@ export class MapViewNode extends Node {
     this._stats = stats;
     this._painted = true;
     this._controller.painting = false;
+    this._controller.paintEnded();
     this._frameClip = null;
     void frame;
     this._prop<(stats: MapFrameStats) => void>('onFrame')?.(stats);
@@ -965,7 +989,8 @@ export class MapViewNode extends Node {
     pane: ScreenRect,
     stats: MapFrameStats,
     budget: number,
-    started: number,
+    /** When this frame began, on {@link restyleClock}. */
+    began: number,
     whole: boolean,
     progressive: boolean,
   ): void {
@@ -985,9 +1010,9 @@ export class MapViewNode extends Node {
     // next frame after it begins.
     if (budget > 0) {
       if (outgoing.lastDrawn !== null) {
-        outgoing.waited += started - outgoing.lastDrawn;
+        outgoing.waited += began - outgoing.lastDrawn;
       }
-      outgoing.lastDrawn = started;
+      outgoing.lastDrawn = began;
     } else {
       outgoing.lastDrawn = null;
     }
@@ -1264,10 +1289,13 @@ export class MapViewNode extends Node {
       // background — with the labels and the markers still drawn over it —
       // until the coarser tile had been fetched, rasterized and composited.
       //
-      // Descendants win when they cover the whole square, because they are
-      // sharper and they are the level the user is coming *from*; the
-      // ancestor wins when they do not, because a complete blurry picture
-      // beats a sharp one with holes in it.
+      // Both, in one square: the descendants wherever there are any, because
+      // they are sharper and they are the level the user is coming *from*,
+      // and the ancestor in the gaps between them. The first cut chose one
+      // for the whole square — descendants only when they tiled it, and
+      // only when no ancestor was in hand — and a zoom out lands at the
+      // edges of the level it left, where they never tile it: that was the
+      // background there, sharp tiles in hand or not.
       //
       // Looked up whether or not this pass draws the tile, because the
       // lookup is what stamps a piece as in use: a piece covering a hole is
@@ -1275,60 +1303,65 @@ export class MapViewNode extends Node {
       // — which, in the one-pixel frames a redraw runs in, was every piece
       // but the one under that pixel. A restyle keeps such pieces on screen
       // for as long as its redraw takes.
-      const kids = this._cache.descendantsWithSurface(
+      const below = this._cache.descendantsWithSurface(
         source,
         entry.tile,
-        undefined,
         generation,
       );
-      const covered =
-        kids.length > 0 && kids.length === kids[0].span * kids[0].span;
-      const ancestor = covered
-        ? null
-        : this._cache.ancestorWithSurface(
-            source,
-            entry.tile,
-            undefined,
-            generation,
-          );
+      const ancestor =
+        below.gaps.length > 0
+          ? this._cache.ancestorWithSurface(
+              source,
+              entry.tile,
+              undefined,
+              generation,
+            )
+          : null;
       if (!inPass) continue;
-      if (ancestor?.shown) {
-        const up = entry.tile.z - ancestor.tile.z;
+      for (const piece of below.pieces) {
+        const edge = entry.size / piece.span;
+        this._composite(
+          ctx,
+          piece.value.shown!.surface,
+          piece.value.shown!.size,
+          {
+            x: box.x + piece.x * edge,
+            y: box.y + piece.y * edge,
+            width: edge,
+            height: edge,
+          },
+          scale,
+          0,
+          0,
+          1,
+        );
+      }
+      if (below.pieces.length > 0) stats.fromDescendant++;
+      if (!ancestor?.shown) continue;
+      for (const gap of below.gaps) {
+        // The gap is a tile `log2(span)` levels under this one, and the
+        // ancestor is `up` levels over that: the same sub-square arithmetic
+        // as a whole tile, one level set deeper.
+        const edge = entry.size / gap.span;
+        const up = entry.tile.z + Math.log2(gap.span) - ancestor.tile.z;
         const span = 1 << up;
-        const fx = entry.tile.x - (ancestor.tile.x << up);
-        const fy = entry.tile.y - (ancestor.tile.y << up);
         this._composite(
           ctx,
           ancestor.shown.surface,
           ancestor.shown.size,
-          box,
+          {
+            x: box.x + gap.x * edge,
+            y: box.y + gap.y * edge,
+            width: edge,
+            height: edge,
+          },
           scale,
-          fx,
-          fy,
+          entry.tile.x * gap.span + gap.x - (ancestor.tile.x << up),
+          entry.tile.y * gap.span + gap.y - (ancestor.tile.y << up),
           span,
         );
-        stats.fromAncestor++;
-      } else if (kids.length > 0) {
-        for (const kid of kids) {
-          const piece = entry.size / kid.span;
-          this._composite(
-            ctx,
-            kid.entry.shown!.surface,
-            kid.entry.shown!.size,
-            {
-              x: box.x + kid.x * piece,
-              y: box.y + kid.y * piece,
-              width: piece,
-              height: piece,
-            },
-            scale,
-            0,
-            0,
-            1,
-          );
-        }
-        stats.fromDescendant++;
       }
+      stats.fromAncestor++;
     }
   }
 

package/src/maps/proj.ts

@@ -472,6 +472,93 @@ export function dataSquareOf(
   };
 }
 
+/**
+ * How many levels under a hole {@link fillFromBelow} looks for pieces.
+ *
+ * A zoom out leaves the level it came from in the middle of the view, and a
+ * quick one — a flick of the wheel, a pinch — goes more than one level
+ * before a single coarser tile has landed. Four levels down, a tile's pieces
+ * are a sixteenth of its width; past that they cover too little of the view
+ * to be worth the search.
+ */
+export const FILL_DEPTH = 4;
+
+/** Part of a tile's square: cell `(x, y)` of a `span × span` grid. */
+export interface TileCell {
+  x: number;
+  y: number;
+  span: number;
+}
+
+/** What a {@link fillFromBelow} probe answers for a tile that has nothing
+ *  of its own to draw but may have something under it. */
+export const BELOW: unique symbol = Symbol('below');
+
+/**
+ * Cover a hole — a tile with nothing of its own to draw — from the tiles
+ * under it that do have something: each quarter of the square from its own
+ * child where there is one, and from that child's children where there is
+ * not, down to `depth` levels. What is left is the gaps, for the caller to
+ * fill from an ancestor.
+ *
+ * `probe` answers for one tile under the hole: something to draw; `null`
+ * for a tile that is answered and has nothing in it, which covers its
+ * square as surely as a picture does; {@link BELOW} for nothing here but
+ * perhaps something under it; `undefined` for nothing here or under it.
+ *
+ * The pieces and the gaps tile the square exactly and never overlap, so a
+ * caller can draw each once with no clip but its own square. That matters
+ * beyond overdraw: a translucent layer drawn twice is darker, and a label
+ * from two overlapping pieces is placed twice. And a square with nothing
+ * under it after all is one gap, not four, so the ancestor that fills it is
+ * one composite.
+ */
+export function fillFromBelow<T>(
+  tile: TileId,
+  depth: number,
+  probe: (tile: TileId) => T | null | typeof BELOW | undefined,
+): {
+  pieces: (TileCell & { tile: TileId; value: T })[];
+  gaps: TileCell[];
+  /** Whether any of the square is covered — by a picture, or by an answer
+   *  that there is nothing there. */
+  covered: boolean;
+} {
+  const pieces: (TileCell & { tile: TileId; value: T })[] = [];
+  const gaps: TileCell[] = [];
+  const visit = (parent: TileId, at: TileCell, left: number): boolean => {
+    const gapsBefore = gaps.length;
+    let covered = false;
+    for (let dy = 0; dy < 2; dy++) {
+      for (let dx = 0; dx < 2; dx++) {
+        const child = {
+          z: parent.z + 1,
+          x: parent.x * 2 + dx,
+          y: parent.y * 2 + dy,
+        };
+        const cell = { x: at.x * 2 + dx, y: at.y * 2 + dy, span: at.span * 2 };
+        const found = probe(child);
+        if (found === BELOW) {
+          if (left > 1 && visit(child, cell, left - 1)) covered = true;
+          else gaps.push(cell);
+        } else if (found === undefined) {
+          gaps.push(cell);
+        } else {
+          if (found !== null)
+            pieces.push({ ...cell, tile: child, value: found });
+          covered = true;
+        }
+      }
+    }
+    // Nothing anywhere under this square: the caller files it as one gap.
+    if (!covered) gaps.length = gapsBefore;
+    return covered;
+  };
+  const covered = depth > 0 && visit(tile, { x: 0, y: 0, span: 1 }, depth);
+  if (!covered) gaps.push({ x: 0, y: 0, span: 1 });
+  return { pieces, gaps, covered };
+}
+
 /**
  * How large to rasterize a tile whose pyramid level is `z` at camera `zoom`.
  *

package/src/maps/sources.ts

@@ -238,10 +238,12 @@ export function osmVectorSource(options: OsmSourceOptions): MapSource {
  * and it is already installed:
  *
  * ```ts
- * import ntk from 'react-x11/ntk';
+ * import * as ntk from 'react-x11/ntk';
+ * // a named export, not a property of the default one, and undeclared
+ * const { decodeImage } = ntk as unknown as { decodeImage(b: Uint8Array): {
+ *   width: number; height: number; data: Uint8Array } };
  * const decode = (bytes) => {
- *   const image = (ntk as { decodeImage(b: Uint8Array): {
- *     width: number; height: number; data: Uint8Array } }).decodeImage(bytes);
+ *   const image = decodeImage(bytes);
  *   return { width: image.width, height: image.height, data: image.data };
  * };
  * ```

package/src/maps/style.ts

@@ -23,6 +23,7 @@
 // the whole performance argument for the restriction: a dense tile has
 // twelve thousand features and eighteen layers, so anything computed per
 // layer is free and anything computed per feature is the frame.
+import type { MapIcon } from './icons.js';
 import type { FeatureValue } from './mvt.js';
 import { GeomType } from './mvt.js';
 import type { FeatureCursor } from './mvt.js';
@@ -151,6 +152,37 @@ export interface SymbolLayer extends LayerBase {
    * distance is where that line goes.
    */
   repeatDistance?: number;
+  /**
+   * A pictogram set on the point, with the text beside it — the bus that
+   * says "Lyons Ave/Yuille St" is a stop, not a street. The icon is centred
+   * on the feature and the text sits to its right; the two are placed, and
+   * give way, as one. Point labels only: a name along a street has no point
+   * to stand an icon on, and is set as though there were none.
+   *
+   * One icon per layer, like {@link rank} and for the same reason — a
+   * `filter` split says which features get which, exactly.
+   */
+  icon?: MapIcon;
+  /** Logical pixels across the icon's plate. 14 by default. */
+  iconSize?: Zoomed<number>;
+  /** The plate's colour. */
+  iconColor?: Zoomed<string>;
+  /** The pictogram's colour, over the plate. White by default. */
+  iconGlyphColor?: Zoomed<string>;
+  /**
+   * Move each point label into the polygon of `sourceLayer` it belongs to —
+   * a house number into its house. A point inside a polygon belongs to it;
+   * one outside, to the nearest polygon within `within` metres (15 by
+   * default). It moves only where it is the one point that polygon is
+   * claimed by, and then to the polygon's middle; every other point stays
+   * where the data put it. Absent, nothing moves.
+   *
+   * Worth having because address data is often not *on* its building: an
+   * address point sits in the lot, metres from the house, and a number
+   * drawn there reads as the garden's. On OpenStreetMap's tiles around
+   * Melbourne, 42% of address points were inside a building.
+   */
+  snapInto?: { sourceLayer: string; within?: number };
 }
 
 export type MapStyleLayer = FillLayer | LineLayer | CircleLayer | SymbolLayer;

package/src/maps/styles.ts

@@ -19,7 +19,14 @@
 // Every layer's `id` is stable, because that is what an application filters
 // on to hide one (`style.layers.filter((l) => l.id !== 'buildings')`) and
 // what a `<Map>` event names.
-import type { MapStyle, MapStyleLayer, Zoomed } from './style.js';
+import type { MapIcon } from './icons.js';
+import type {
+  MapFilter,
+  MapStyle,
+  MapStyleLayer,
+  SymbolLayer,
+  Zoomed,
+} from './style.js';
 
 /** The tags Shortbread puts a road's class in, grouped as a style wants
  *  them rather than as the schema lists them. */
@@ -108,6 +115,8 @@ export interface MapPalette {
   text: string;
   textMinor: string;
   halo: string;
+  /** The plate a public-transport stop's pictogram is set on. */
+  transit: string;
 }
 
 /** OSM Carto's hues, near enough that a user's eye reads the map as the one
@@ -135,6 +144,7 @@ export const LIGHT_PALETTE: MapPalette = {
   text: '#33322e',
   textMinor: '#6b6862',
   halo: 'rgba(255,255,255,0.85)',
+  transit: '#2a6fb8',
 };
 
 /** The dark counterpart. Desaturated rather than inverted: an inverted map
@@ -162,6 +172,7 @@ export const DARK_PALETTE: MapPalette = {
   text: '#d3d7de',
   textMinor: '#9299a3',
   halo: 'rgba(12,14,18,0.85)',
+  transit: '#3b78c4',
 };
 
 /** How wide a road class is, at each zoom. */
@@ -190,6 +201,16 @@ export interface ShortbreadStyleOptions {
   /** Leave building footprints out. They are the densest polygon layer at
    *  high zoom and the first thing to drop on a slow machine. */
   buildings?: boolean;
+  /**
+   * Set each house number inside its building (`SymbolLayer.snapInto` on
+   * the `house-numbers` layer), where the address data puts it in the lot
+   * beside the house. Off by default, and off means every number is exactly
+   * where the data says. A number moves only into a building that is its
+   * alone and within 15 m, so a duplex's two numbers, or one whose house is
+   * not mapped, stay put. Needs the footprints: with `buildings: false`
+   * there is nothing to set a number in, and nothing moves.
+   */
+  snapBuildingNumbers?: boolean;
 }
 
 /**
@@ -593,11 +614,29 @@ export function shortbreadStyle(
         // a street's name is what they read once they are oriented.
         rank: 20,
       },
+      // Public transport, a layer per pictogram, which Shortbread's `kind`
+      // says. A stop's name alone reads as a street's: "Lyons Ave/Yuille
+      // St" is a bus stop, and only the bus says so.
+      ...SHORTBREAD_STOPS.map((stop) =>
+        stopLayer(
+          p,
+          name,
+          stop.id,
+          'public_transport',
+          ['in', 'kind', ...stop.kinds],
+          stop.icon,
+          stop.minZoom,
+          stop.rank,
+        ),
+      ),
       {
+        // What has no pictogram here — a helipad, a lift station — named
+        // as every stop used to be.
         id: 'transport-labels',
         type: 'symbol',
         sourceLayer: 'public_transport',
         minZoom: 15,
+        filter: ['!in', 'kind', ...SHORTBREAD_STOPS.flatMap((s) => s.kinds)],
         textField: name,
         textColor: p.textMinor,
         textHaloColor: p.halo,
@@ -605,6 +644,7 @@ export function shortbreadStyle(
         textSize: 10,
         rank: 10,
       },
+      houseNumbers(p, 'addresses', snapInto(options, 'buildings')),
     );
   }
 
@@ -618,6 +658,121 @@ function scaleWidth(base: Zoomed<number>, add: number): Zoomed<number> {
   return { stops: base.stops.map(([z, v]) => [z, v + add] as const) };
 }
 
+/** Shortbread's public-transport kinds that have a pictogram, and the zoom
+ *  and rank a stop of each is named at: an airport among the towns, a
+ *  station among the suburbs, a bus stop under the streets. */
+const SHORTBREAD_STOPS: readonly {
+  id: string;
+  kinds: readonly string[];
+  icon: MapIcon;
+  minZoom: number;
+  rank: number;
+}[] = [
+  {
+    id: 'transport-airport',
+    kinds: ['aerodrome'],
+    icon: 'airport',
+    minZoom: 11,
+    rank: 70,
+  },
+  {
+    id: 'transport-rail',
+    kinds: ['station', 'halt'],
+    icon: 'train',
+    minZoom: 13,
+    rank: 50,
+  },
+  {
+    id: 'transport-ferry',
+    kinds: ['ferry_terminal'],
+    icon: 'ferry',
+    minZoom: 13,
+    rank: 45,
+  },
+  {
+    id: 'transport-tram',
+    kinds: ['tram_stop'],
+    icon: 'tram',
+    minZoom: 15,
+    rank: 12,
+  },
+  {
+    id: 'transport-bus',
+    kinds: ['bus_stop', 'bus_station'],
+    icon: 'bus',
+    minZoom: 15,
+    rank: 10,
+  },
+];
+
+/** A public-transport stop: its pictogram on the point, its name beside
+ *  it. The same layer over either schema, less where the schema keeps it. */
+function stopLayer(
+  p: MapPalette,
+  name: string,
+  id: string,
+  sourceLayer: string,
+  filter: MapFilter | undefined,
+  icon: MapIcon,
+  minZoom: number,
+  rank: number,
+): SymbolLayer {
+  return {
+    id,
+    type: 'symbol',
+    sourceLayer,
+    minZoom,
+    filter,
+    textField: name,
+    textColor: p.textMinor,
+    textHaloColor: p.halo,
+    textHaloWidth: 1,
+    textSize: 10,
+    icon,
+    iconColor: p.transit,
+    rank,
+  };
+}
+
+/** The footprints house numbers snap into, where the options ask for it and
+ *  the footprints are there to snap into. */
+function snapInto(
+  options: ShortbreadStyleOptions,
+  buildings: string,
+): string | null {
+  return options.snapBuildingNumbers && options.buildings !== false
+    ? buildings
+    : null;
+}
+
+/**
+ * House numbers, once a house is big enough on screen to carry one: from
+ * zoom 18, which on this map's 512-pixel world is a 256-pixel map's 19 —
+ * where Google Maps sets them.
+ */
+function houseNumbers(
+  p: MapPalette,
+  sourceLayer: string,
+  buildings: string | null,
+): SymbolLayer {
+  return {
+    id: 'house-numbers',
+    type: 'symbol',
+    sourceLayer,
+    ...(buildings ? { snapInto: { sourceLayer: buildings } } : {}),
+    minZoom: 18,
+    textField: 'housenumber',
+    textColor: p.textMinor,
+    textHaloColor: p.halo,
+    textHaloWidth: 1,
+    textSize: 10,
+    // Under every other name, and held to no repeat distance: "2" is the
+    // number of a house on every street there is.
+    rank: 0,
+    repeatDistance: 0,
+  };
+}
+
 // --- OpenMapTiles -----------------------------------------------------------
 
 /**
@@ -682,9 +837,6 @@ export function openMapTilesStyle(
   };
   const name = options.nameField ?? 'name';
   const layers: MapStyleLayer[] = [
-    // One `water` layer for everything wet, with `class` telling the sea
-    // from a lake — where Shortbread has `ocean` and `water_polygons`.
-    { id: 'ocean', type: 'fill', sourceLayer: 'water', color: p.water },
     {
       id: 'landuse-green',
       type: 'fill',
@@ -708,6 +860,18 @@ export function openMapTilesStyle(
       filter: ['in', 'class', ...OMT_SITES],
       color: p.site,
     },
+    // One `water` layer for everything wet, with `class` telling the sea
+    // from a lake — where Shortbread has `ocean` and `water_polygons`.
+    //
+    // Drawn **over** the green and the built-up, as Shortbread's
+    // `water_polygons` are and as OSM Bright and OSM Liberty draw it. This
+    // schema has no land polygons — land is the background and the sea is
+    // cut out of it — and its `park` layer carries protected areas, which
+    // are often mostly sea: the Pearl River Estuary's dolphin reserve is a
+    // rectangle of water west of Lantau. Drawn first, the sea went under
+    // every park that reaches into it, and under every one with a lake in
+    // it.
+    { id: 'ocean', type: 'fill', sourceLayer: 'water', color: p.water },
     {
       id: 'water-lines',
       type: 'line',
@@ -1033,6 +1197,53 @@ export function openMapTilesStyle(
         textSize: 11,
         rank: 20,
       },
+      // Public transport, from `poi`'s classes — OpenMapTiles has no layer
+      // of its own for it — and airports from theirs.
+      stopLayer(
+        p,
+        name,
+        'transport-airport',
+        'aerodrome_label',
+        undefined,
+        'airport',
+        11,
+        70,
+      ),
+      stopLayer(
+        p,
+        name,
+        'transport-rail',
+        'poi',
+        [
+          'all',
+          ['==', 'class', 'railway'],
+          ['in', 'subclass', 'station', 'halt'],
+        ],
+        'train',
+        13,
+        50,
+      ),
+      stopLayer(
+        p,
+        name,
+        'transport-tram',
+        'poi',
+        ['==', 'subclass', 'tram_stop'],
+        'tram',
+        15,
+        12,
+      ),
+      stopLayer(
+        p,
+        name,
+        'transport-bus',
+        'poi',
+        ['==', 'class', 'bus'],
+        'bus',
+        15,
+        10,
+      ),
+      houseNumbers(p, 'housenumber', snapInto(options, 'building')),
     );
   }