@react-x11/components 0.8.0 → 0.9.0

package/src/maps/overlay.ts

@@ -18,7 +18,7 @@ import { clipOf, clipRing, clipSegment } from './clip.js';
 import type { ClipRect } from './clip.js';
 import type { MapCanvas } from './paint.js';
 import { projectLngLat } from './proj.js';
-import type { LngLat, Transform } from './proj.js';
+import type { LngLat, ScreenRect, Transform } from './proj.js';
 
 /** A point on the map the user can click. */
 export interface MapMarker {
@@ -37,9 +37,11 @@ export interface MapMarker {
   /** The ring around it, so a marker stays visible on any basemap. The
    *  theme's background by default. */
   outline?: string;
-  /** Drawn above unselected markers, and given the selected ring. */
+  /** Drawn above the unselected markers of its `zIndex`, and given the
+   *  selected ring: 2.5 logical pixels of the theme's text colour. */
   selected?: boolean;
-  /** Higher draws later. Ties break on array order. */
+  /** Higher draws later, and is hit first. Ties break on `selected`, then
+   *  on array order. */
   zIndex?: number;
   /** Skipped by hit testing — for a marker that is decoration. */
   interactive?: boolean;
@@ -104,12 +106,56 @@ export interface OverlayPalette {
   text: string;
 }
 
+/** The attribution's text size, in logical pixels. */
+export const ATTRIBUTION_SIZE = 9;
+/** The opacity of the box of the theme's background the attribution sits
+ *  in — enough to read it over any basemap, not so much that it hides one. */
+export const ATTRIBUTION_OPACITY = 0.72;
+
+/**
+ * Where the attribution goes: a box in the pane's bottom-right corner with 4
+ * logical pixels of padding either side of the text and 2 above and below
+ * it, and the text's top-left corner inside it — in device pixels, on whole
+ * ones. Both renderers lay it out with this, so it sits on the same pixels
+ * whichever of them draws the map.
+ *
+ * `text` is the set string's box and `pane` the pane, in logical pixels.
+ */
+export function attributionLayout(
+  text: { width: number; height: number },
+  pane: ScreenRect,
+  scale: number,
+): { box: ScreenRect; x: number; y: number } {
+  const padding = 4;
+  const width = text.width + padding * 2;
+  const height = text.height + padding;
+  const x = pane.x + pane.width - width;
+  const y = pane.y + pane.height - height;
+  return {
+    box: {
+      x: Math.round(x * scale),
+      y: Math.round(y * scale),
+      width: Math.ceil(width * scale),
+      height: Math.ceil(height * scale),
+    },
+    x: Math.round((x + padding) * scale),
+    y: Math.round((y + padding / 2) * scale),
+  };
+}
+
 function byZ<T extends { zIndex?: number }>(items: readonly T[]): T[] {
   // A stable sort — the language guarantees it — so items with no `zIndex`
   // keep the order the application listed them in.
   return [...items].sort((a, b) => (a.zIndex ?? 0) - (b.zIndex ?? 0));
 }
 
+/** The order overlays are drawn in, bottom first: by `zIndex`, and
+ *  otherwise the order the application listed them in. Both renderers
+ *  draw in it. */
+export function overlayOrder(overlays: readonly MapOverlay[]): MapOverlay[] {
+  return byZ(overlays);
+}
+
 /**
  * Draw the overlays.
  *
@@ -314,22 +360,87 @@ function appendRing(ctx: MapCanvas, ring: readonly number[]): boolean {
   return true;
 }
 
-/** Where a marker's ink lands, in pane-local logical pixels. Shared by the
- *  drawing and the hit test, so the two cannot disagree — the bug that
- *  makes a marker unclickable a few pixels from where it looks. */
-export function markerRect(
+/** A marker's size when it names none, in logical pixels. */
+export const MARKER_SIZE = 14;
+/** A pin is this many times as tall as it is wide. */
+export const PIN_HEIGHT = 1.4;
+
+/**
+ * The order markers are drawn in, bottom first: by `zIndex`, a selected
+ * marker above the unselected ones of its `zIndex`, and otherwise the order
+ * the application listed them in. The hit test walks it from the top, so a
+ * press lands on the marker drawn over the others. Both renderers draw in
+ * it.
+ */
+export function markerOrder(markers: readonly MapMarker[]): MapMarker[] {
+  // A stable sort, so equal keys keep the application's order.
+  return [...markers].sort(
+    (a, b) =>
+      (a.zIndex ?? 0) - (b.zIndex ?? 0) ||
+      Number(a.selected === true) - Number(b.selected === true),
+  );
+}
+
+/** A marker's colours and ring, the theme's where it names none — what
+ *  both renderers paint it with. `ringWidth` is in device pixels. */
+export function markerPaint(
   marker: MapMarker,
-  transform: Transform,
-): {
+  palette: OverlayPalette,
+  scale: number,
+): { fill: string; ring: string; ringWidth: number } {
+  return {
+    fill: marker.color ?? palette.accent,
+    ring: marker.selected
+      ? palette.text
+      : (marker.outline ?? palette.background),
+    ringWidth: Math.max(1, (marker.selected ? 2.5 : 1.5) * scale),
+  };
+}
+
+/** Where a marker's ink lands: its box, and the point it marks. */
+export interface MarkerRect {
   x: number;
   y: number;
   width: number;
   height: number;
   tipX: number;
   tipY: number;
-} {
+}
+
+/**
+ * The markers a pane shows, bottom first, with where each one's ink lands
+ * — what both renderers draw. A marker wholly outside the pane is left out.
+ */
+export function markersInView(
+  markers: readonly MapMarker[],
+  transform: Transform,
+  pane: { width: number; height: number },
+): { marker: MapMarker; rect: MarkerRect }[] {
+  const shown: { marker: MapMarker; rect: MarkerRect }[] = [];
+  for (const marker of markerOrder(markers)) {
+    const rect = markerRect(marker, transform);
+    if (
+      rect.x + rect.width < 0 ||
+      rect.y + rect.height < 0 ||
+      rect.x > pane.width ||
+      rect.y > pane.height
+    ) {
+      continue;
+    }
+    shown.push({ marker, rect });
+  }
+  return shown;
+}
+
+/** Where a marker's ink lands, in pane-local logical pixels. Shared by the
+ *  drawing and the hit test, so the two cannot disagree — the bug that
+ *  makes a marker unclickable a few pixels from where it looks. */
+export function markerRect(
+  marker: MapMarker,
+  transform: Transform,
+): MarkerRect {
   const point = projectLngLat(transform, marker.position);
-  const size = marker.size ?? 14;
+  const size = marker.size ?? MARKER_SIZE;
   if ((marker.shape ?? 'pin') === 'circle') {
     return {
       x: point.x - size / 2,
@@ -343,7 +454,7 @@ export function markerRect(
   // A pin *stands on* its position: the point is the tip, and the head is
   // above it. Getting this the other way round puts every marker half its
   // own height north of where it belongs, which on a city map is a street.
-  const height = size * 1.4;
+  const height = size * PIN_HEIGHT;
   return {
     x: point.x - size / 2,
     y: point.y - height,
@@ -354,7 +465,7 @@ export function markerRect(
   };
 }
 
-/** Draw the markers, lowest `zIndex` first. */
+/** Draw the markers, in {@link markerOrder}. */
 export function drawMarkers(
   ctx: MapCanvas,
   markers: readonly MapMarker[],
@@ -363,27 +474,17 @@ export function drawMarkers(
   scale: number,
   palette: OverlayPalette,
 ): number {
-  let drawn = 0;
-  for (const marker of byZ(markers)) {
-    const rect = markerRect(marker, transform);
-    if (
-      rect.x + rect.width < 0 ||
-      rect.y + rect.height < 0 ||
-      rect.x > pane.width ||
-      rect.y > pane.height
-    ) {
-      continue;
-    }
-    const size = marker.size ?? 14;
-    const fill = marker.color ?? palette.accent;
-    const ring = marker.outline ?? palette.background;
+  const shown = markersInView(markers, transform, pane);
+  for (const { marker, rect } of shown) {
+    const size = marker.size ?? MARKER_SIZE;
+    const paint = markerPaint(marker, palette, scale);
     const x = (pane.x + rect.tipX) * scale;
     const y = (pane.y + rect.tipY) * scale;
     const r = (size / 2) * scale;
     ctx.save();
-    ctx.lineWidth = Math.max(1, (marker.selected ? 2.5 : 1.5) * scale);
-    ctx.strokeStyle = marker.selected ? palette.text : ring;
-    ctx.fillStyle = fill;
+    ctx.lineWidth = paint.ringWidth;
+    ctx.strokeStyle = paint.ring;
+    ctx.fillStyle = paint.fill;
     if ((marker.shape ?? 'pin') === 'circle') {
       ctx.beginPath();
       ctx.moveTo(x + r, y);
@@ -391,12 +492,14 @@ export function drawMarkers(
       ctx.fill();
       ctx.stroke();
     } else {
-      // A teardrop: a circle for the head and two lines down to the tip.
-      // The tangent angle is where the straight sides meet the circle, so
-      // the outline is smooth rather than two lines crossing an arc.
-      const cy = y - size * 1.4 * scale + r;
+      // A teardrop: a circle for the head and two straight sides down to
+      // the tip, meeting the circle where they are tangent to it — at
+      // acos(r / d) either side of the line to the tip, seen from the
+      // centre — so the outline is smooth rather than two lines crossing
+      // an arc.
+      const cy = y - size * PIN_HEIGHT * scale + r;
       const d = y - cy;
-      const angle = Math.asin(Math.min(1, r / d));
+      const angle = Math.acos(Math.min(1, r / d));
       ctx.beginPath();
       ctx.arc(x, cy, r, Math.PI / 2 + angle, Math.PI / 2 - angle);
       ctx.lineTo(x, y);
@@ -405,9 +508,8 @@ export function drawMarkers(
       ctx.stroke();
     }
     ctx.restore();
-    drawn++;
   }
-  return drawn;
+  return shown.length;
 }
 
 /** The marker under a pane-local logical point, topmost first, or null. */
@@ -418,7 +520,7 @@ export function markerAt(
   y: number,
   slop = 2,
 ): MapMarker | null {
-  const ordered = byZ(markers);
+  const ordered = markerOrder(markers);
   for (let i = ordered.length - 1; i >= 0; i--) {
     const marker = ordered[i];
     if (marker.interactive === false) continue;
@@ -623,13 +725,16 @@ export function geoJsonOverlays(
  */
 const MAX_ARC_RADIUS = 8192;
 
+/** How many segments a circle of this radius, in pixels, is drawn with as
+ *  a ring: enough to hold the sagitta under half a pixel. */
+export function circleSegments(radius: number): number {
+  const step = 2 * Math.acos(Math.max(-1, 1 - 0.5 / radius));
+  return Math.min(4096, Math.max(24, Math.ceil((Math.PI * 2) / step)));
+}
+
 /** A circle as a ring, with the sagitta held under half a pixel. */
 function circleRing(cx: number, cy: number, radius: number): number[] {
-  const step = 2 * Math.acos(Math.max(-1, 1 - 0.5 / radius));
-  const segments = Math.min(
-    4096,
-    Math.max(24, Math.ceil((Math.PI * 2) / step)),
-  );
+  const segments = circleSegments(radius);
   const out: number[] = [];
   for (let i = 0; i < segments; i++) {
     const angle = (i / segments) * Math.PI * 2;

package/src/maps/paint.ts

@@ -72,6 +72,9 @@ export interface MapCanvas {
    *  scale bar are drawn with. */
   fillRects?(rects: readonly number[]): void;
   setLineDash?(segments: readonly number[]): void;
+  /** What a street name set along its street is drawn with. */
+  translate?(x: number, y: number): void;
+  rotate?(angle: number): void;
   roundRect?(x: number, y: number, w: number, h: number, radii: number): void;
   drawImage?(image: unknown, ...args: number[]): void;
   /** Straight RGBA in, for a raster tile the application decoded. */

package/src/maps/proj.ts

@@ -441,6 +441,37 @@ export function subTileOf(
   };
 }
 
+/**
+ * Where the data tile that serves a cover entry lands on screen: the entry
+ * itself until the cover goes deeper than the source cuts, and past that
+ * the whole of the ancestor it is one cell of — `span` times its size,
+ * starting `sub.x` cells to its left and `sub.y` above it.
+ *
+ * What a **raster** tile is drawn over past its source's depth. A vector
+ * cell is rasterized from its data tile's features through the cell, which
+ * is where overzoom's sharpness comes from; an image has nothing finer in
+ * it, so it is drawn whole, once, over this square. Placed from the entry
+ * rather than from the camera, and it lands where {@link tileCover} at the
+ * source's own depth puts the same tile.
+ */
+export function dataSquareOf(
+  entry: TileCoverEntry,
+  maxZoom: number,
+): TileCoverEntry {
+  const sub = subTileOf(entry.tile, maxZoom);
+  if (sub.span === 1) return entry;
+  return {
+    tile: dataTileFor(entry.tile, maxZoom),
+    worldCopy: entry.worldCopy,
+    x: entry.x - sub.x * entry.size,
+    y: entry.y - sub.y * entry.size,
+    size: entry.size * sub.span,
+    // The cell's: a square takes its place in the cover's order from the
+    // cell it was reached through.
+    distance: entry.distance,
+  };
+}
+
 /**
  * How large to rasterize a tile whose pyramid level is `z` at camera `zoom`.
  *

package/src/maps/renderer.ts

@@ -0,0 +1,155 @@
+// Which of `<Map>`'s two renderers draws a map, and bringing the GL one in.
+//
+// The retained renderer (`./node.ts`) runs everywhere a 2D context does —
+// indirect GLX, a remote X server, Xvfb in CI, the headless harness — and
+// is visible to window capture. The GL renderer (`./gl/`) needs direct GL,
+// and draws every frame from vector data at the display's rate. Neither is
+// deprecated in favour of the other: `docs/prd-maps-gl.md`, "One `<Map>`,
+// two renderers", has why the retained one stays, and this file is the
+// decision between them — pure, so the whole of it is a unit test.
+//
+// `'auto'` decides in this order:
+//
+//  1. An explicit `renderer`, or the environment's, over both props and
+//     policy — the way `REACT_X11_BACKEND` works for the backend.
+//  2. Whether this connection draws through the direct backend at all —
+//     `useSupports('shaders')`, which on X11 needs `glPolicy: 'auto'` and a
+//     DRI3 or Apple-DRI server, and on the Cocoa backend is always true once
+//     its probe has answered.
+//  3. At run time, a GL failure moves the map to the retained renderer, with
+//     its camera and its handle intact. That one is sticky.
+//
+// A map that asked for `'gl'` by name never falls back: it gets GL, or it
+// gets `onError`.
+import type {
+  MapRenderer,
+  MapRendererReason,
+  MapRendererRequest,
+} from './types.js';
+
+/** The environment variable that overrides every map's renderer. */
+export const RENDERER_ENV = 'REACT_X11_MAP_RENDERER';
+
+/**
+ * What a map asks for when it does not say: GL where this connection draws
+ * through the direct backend, the retained renderer everywhere else — which
+ * is still every indirect GLX connection, every remote X server and every
+ * headless test run. `'retained'` until the GL renderer had soaked on both
+ * backends (`docs/prd-maps-gl.md`, "The soak").
+ */
+export const DEFAULT_RENDERER: MapRendererRequest = 'auto';
+
+const REQUESTS: readonly string[] = ['auto', 'gl', 'retained'];
+
+/** Everything the decision reads. */
+export interface RendererInput {
+  /** The `renderer` prop. */
+  requested?: MapRendererRequest;
+  /** `REACT_X11_MAP_RENDERER`, as the environment has it — anything but
+   *  the three names is ignored. */
+  env?: string;
+  /** `useSupports('shaders')`: does this connection draw through the
+   *  direct backend? */
+  shaders: boolean;
+  /**
+   * Whether the answer to that is still to come. The Cocoa backend settles
+   * it on the first ask rather than at connect, so the first render of a map
+   * there reads `false` for an answer that is about to be `true`; drawing
+   * the retained renderer for those few milliseconds would fetch the view's
+   * tiles twice. A map in that state shows its background and waits.
+   */
+  probing?: boolean;
+  /** Whether GL has already failed on this map. */
+  failed: boolean;
+}
+
+/** The decision: a renderer — or `'pending'` while the connection's answer
+ *  is still to come — and why, when it is not what was asked for. */
+export interface RendererChoice {
+  renderer: MapRenderer | 'pending';
+  /** Null when the map got what it asked for. */
+  reason: MapRendererReason | null;
+  /** What was asked for, the environment's word included. */
+  asked: MapRendererRequest;
+}
+
+function requestOf(value: string | undefined): MapRendererRequest | null {
+  const v = value?.trim().toLowerCase();
+  return v && REQUESTS.includes(v) ? (v as MapRendererRequest) : null;
+}
+
+/**
+ * What a map asks for: the environment's word over the prop's, the prop's
+ * over the default — and whether the environment is what changed it.
+ */
+export function rendererRequest(
+  requested: MapRendererRequest | undefined,
+  env: string | undefined,
+): { asked: MapRendererRequest; forced: boolean } {
+  const fromEnv = requestOf(env);
+  const own = requested ?? DEFAULT_RENDERER;
+  return { asked: fromEnv ?? own, forced: fromEnv !== null && fromEnv !== own };
+}
+
+/** Choose a map's renderer. */
+export function chooseRenderer(input: RendererInput): RendererChoice {
+  const { asked, forced: byEnv } = rendererRequest(input.requested, input.env);
+  if (asked === 'retained') {
+    return { renderer: 'retained', reason: byEnv ? 'forced' : null, asked };
+  }
+  if (asked === 'gl') {
+    return { renderer: 'gl', reason: byEnv ? 'forced' : null, asked };
+  }
+  if (input.failed) return { renderer: 'retained', reason: 'gl-failed', asked };
+  if (!input.shaders) {
+    return input.probing
+      ? { renderer: 'pending', reason: null, asked }
+      : { renderer: 'retained', reason: 'no-direct-gl', asked };
+  }
+  return { renderer: 'gl', reason: null, asked };
+}
+
+/** The environment's override, read off `globalThis` because `src/` compiles
+ *  with `types: []`. */
+export function rendererFromEnv(): string | undefined {
+  const g = globalThis as {
+    process?: { env?: Record<string, string | undefined> };
+  };
+  return g.process?.env?.[RENDERER_ENV];
+}
+
+// --- the GL renderer, loaded when it is chosen --------------------------------
+
+/**
+ * The GL renderer's module, once it has loaded.
+ *
+ * Reached by dynamic `import()` and never statically: a static import from
+ * `<Map>` would put all of `./gl/` — the shaders, the bucket builder, the
+ * label atlas — into every bundle that uses a map, which is the tree-shaking
+ * promise broken for an application that never draws one through GL.
+ * `test/treeshake.test.ts` holds it to that.
+ */
+export type GlRendererModule = typeof import('./gl/index.js');
+
+let loaded: GlRendererModule | null = null;
+let loading: Promise<GlRendererModule> | null = null;
+
+/** The GL renderer, if it has loaded — so a second map mounts it at once. */
+export function glRendererModule(): GlRendererModule | null {
+  return loaded;
+}
+
+/** Load the GL renderer — once per process, however many maps ask. */
+export function loadGlRenderer(): Promise<GlRendererModule> {
+  loading ??= import('./gl/index.js').then(
+    (module) => (loaded = module),
+    (error: unknown) => {
+      // Asked again next time rather than failing forever on a cached
+      // rejection: a load that failed once is most likely to fail again,
+      // and the map that asked has already fallen back or reported it.
+      loading = null;
+      throw error;
+    },
+  );
+  return loading;
+}

package/src/maps/sources.ts

@@ -27,7 +27,13 @@ export interface TileRequest extends TileId {
    *  loader. */
   sourceId: string;
   /**
-   * Aborted when the tile leaves the view before it arrives.
+   * Aborted when the map stops wanting the tile before it has arrived: it
+   * has been panned or zoomed out of what the map is loading (the view and
+   * a margin around it), its source has been taken out of `sources`, or the
+   * map has unmounted. Whatever an aborted load answers after that, an
+   * `AbortError` included, is ignored rather than reported to
+   * `onTileError`, and a tile that comes back is asked for again with a new
+   * signal.
    *
    * **This is a real `AbortSignal`** on every runtime that has one, which
    * is what makes `fetch(url, { signal })` work — `fetch` rejects anything
@@ -63,8 +69,17 @@ export type TileData =
 
 /** A tile source. */
 export interface MapSource {
-  /** Distinguishes this source's cache entries from another's. Defaults to
-   *  the source's position in the `sources` array. */
+  /**
+   * What this source is called: the `sourceId` its `load` requests carry
+   * and `onTileError` reports. `source-<index>` by default.
+   *
+   * **Not** what its tiles are cached under — that is the source object
+   * itself, because a name is not a provider: two sources may share one,
+   * and a map switched between them must not draw one's tiles as the
+   * other's. The flip side is that a source made anew on every render
+   * starts from an empty cache on every render, so make it once — at
+   * module scope, or in `useMemo`.
+   */
   id?: string;
   /** Fetch, or answer from a cache, or decline. May be async. */
   load(request: TileRequest): TileData | Promise<TileData>;
@@ -87,6 +102,26 @@ export interface MapSource {
   attribution?: string;
 }
 
+/**
+ * What a map says in its corner: the `attribution` prop when it is given —
+ * `''` is the application saying it has put the attribution somewhere else —
+ * and otherwise every source's own, each once, in order. Both renderers draw
+ * this string, because for open data it is a licence condition.
+ */
+export function attributionOf(
+  attribution: string | undefined,
+  sources: readonly MapSource[],
+): string {
+  if (attribution !== undefined) return attribution;
+  const parts: string[] = [];
+  for (const source of sources) {
+    if (source.attribution && !parts.includes(source.attribution)) {
+      parts.push(source.attribution);
+    }
+  }
+  return parts.join(' · ');
+}
+
 /** A source's pyramid, with the defaults filled in. */
 export function pyramidOf(source: MapSource): {
   minZoom: number;

package/src/maps/theme.ts

@@ -0,0 +1,51 @@
+// The theme's say in how a map looks: which of the default style's palettes
+// it gets, and the colours markers, overlays and the attribution fall back
+// to. Both renderers read the theme through these, so a map in a dark
+// application is dark whichever of them draws it.
+import type { OverlayPalette } from './overlay.js';
+import type { MapStyle } from './style.js';
+import { shortbreadStyle } from './styles.js';
+
+const defaults = new Map<boolean, MapStyle>();
+
+/**
+ * The style a map with no `mapStyle` is drawn in: `shortbreadStyle()` in the
+ * theme's light or dark palette. Made once each — a style's identity is
+ * what decides whether the GL renderer rebuilds its tiles.
+ */
+export function defaultStyleFor(dark: boolean): MapStyle {
+  let style = defaults.get(dark);
+  if (!style) {
+    style = shortbreadStyle({ dark });
+    defaults.set(dark, style);
+  }
+  return style;
+}
+
+/**
+ * Whether a theme is dark — the luminance of the surface the map sits on,
+ * the same reading `src/code-editor/`'s token themes make, rather than a flag
+ * nobody sets. A map inside a dark application that stays light is the thing
+ * everyone notices first.
+ */
+export function isDarkTheme(theme: unknown): boolean {
+  const background = (theme as Record<string, unknown> | undefined)?.background;
+  if (typeof background !== 'string') return false;
+  const hex = background.trim();
+  if (!hex.startsWith('#') || hex.length < 7) return false;
+  const r = parseInt(hex.slice(1, 3), 16);
+  const g = parseInt(hex.slice(3, 5), 16);
+  const b = parseInt(hex.slice(5, 7), 16);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b < 128;
+}
+
+/** The colours a marker, an overlay and the attribution use where they do
+ *  not name one. */
+export function overlayPalette(theme: unknown): OverlayPalette {
+  const t = theme as Record<string, unknown> | undefined;
+  return {
+    accent: (t?.accent as string) ?? '#2d6cdf',
+    background: (t?.background as string) ?? '#ffffff',
+    text: (t?.text as string) ?? '#111111',
+  };
+}