@react-x11/components 0.8.0 → 0.10.0

package/src/maps/icons.ts

@@ -0,0 +1,183 @@
+// Icons: the pictogram a symbol layer can set beside a point's name — the
+// bus on a bus stop, so that "Lyons Ave/Yuille St" reads as a stop and not
+// as a street.
+//
+// An icon is two pieces, each one colour: a rounded **plate** in the layer's
+// colour and a **glyph** over it, white by default. Two single-colour pieces
+// rather than one picture because that is what both renderers already draw
+// text as: the retained renderer fills a path, and the GL renderer keeps a
+// coverage raster in its label atlas and colours it in the shader — so an
+// icon is two more of those, and one raster serves every palette.
+//
+// Both renderers trace the same paths from here, the way both take their
+// label anchors from `./anchors.ts`: a map switched from one renderer to the
+// other draws the same bus.
+
+/** The pictograms a symbol layer can name. */
+export type MapIcon = 'bus' | 'tram' | 'train' | 'ferry' | 'airport';
+
+/** Every {@link MapIcon}, for a style editor's picker. */
+export const MAP_ICONS: readonly MapIcon[] = [
+  'bus',
+  'tram',
+  'train',
+  'ferry',
+  'airport',
+];
+
+/** Logical pixels across a plate, where the layer does not say. */
+export const DEFAULT_ICON_SIZE = 14;
+export const DEFAULT_ICON_COLOR = '#2a6fb8';
+export const DEFAULT_ICON_GLYPH_COLOR = '#ffffff';
+/** Logical pixels between an icon's plate and the name set beside it. */
+export const ICON_GAP = 3;
+
+/** The slice of a 2D context an icon is traced with — `MapCanvas`'s, and
+ *  the offscreen surface's the GL atlas rasterizes on. */
+export interface IconPathContext {
+  beginPath(): void;
+  moveTo(x: number, y: number): void;
+  lineTo(x: number, y: number): void;
+  arc(x: number, y: number, r: number, from: number, to: number): void;
+  closePath(): void;
+}
+
+/** The grid a glyph is drawn on: a plate is this many units across. */
+const GRID = 16;
+
+/**
+ * Each glyph as polygons on the {@link GRID}, `[x0, y0, x1, y1, …]`.
+ *
+ * Solid shapes only, and a window is where no shape is: a glyph is filled
+ * with the non-zero rule, where a hole would take a second winding, and
+ * {@link wound} turns every polygon the same way so that two that touch
+ * fill as one rather than cancelling.
+ */
+const GLYPHS: Record<MapIcon, readonly (readonly number[])[]> = {
+  // Head on: a roof, the windscreen between two pillars, the lower panel,
+  // wheels and mirrors.
+  bus: [
+    [4, 3.5, 5, 2.5, 11, 2.5, 12, 3.5, 12, 4.6, 4, 4.6],
+    rect(4, 4.6, 1.2, 4),
+    rect(10.8, 4.6, 1.2, 4),
+    rect(4, 8.6, 8, 3.6),
+    rect(4.6, 12.2, 2, 1.4),
+    rect(9.4, 12.2, 2, 1.4),
+    rect(2.9, 5, 0.8, 2),
+    rect(12.3, 5, 0.8, 2),
+  ],
+  // A car under its pantograph, on rails.
+  tram: [
+    rect(5.4, 1.4, 5.2, 0.8),
+    rect(7.6, 2.2, 0.8, 1.4),
+    [4.5, 4.6, 5.5, 3.6, 10.5, 3.6, 11.5, 4.6, 11.5, 5.4, 4.5, 5.4],
+    rect(4.5, 5.4, 1.1, 3.6),
+    rect(10.4, 5.4, 1.1, 3.6),
+    rect(4.5, 9, 7, 3),
+    [5.6, 12, 6.9, 12, 5.8, 14.2, 4.5, 14.2],
+    [9.1, 12, 10.4, 12, 11.5, 14.2, 10.2, 14.2],
+  ],
+  // A locomotive's rounded nose, with its rails splayed wider than a tram's.
+  train: [
+    [4, 5, 4.6, 3, 6, 2.2, 10, 2.2, 11.4, 3, 12, 5, 12, 5.6, 4, 5.6],
+    rect(4, 5.6, 1.2, 3),
+    rect(10.8, 5.6, 1.2, 3),
+    rect(4, 8.6, 8, 3),
+    [5, 11.6, 6.4, 11.6, 4.8, 14.2, 3.4, 14.2],
+    [9.6, 11.6, 11, 11.6, 12.6, 14.2, 11.2, 14.2],
+  ],
+  // Side on: a hull, a deckhouse, a funnel.
+  ferry: [
+    [2, 9, 14, 9, 12.2, 12.6, 3.8, 12.6],
+    rect(4.4, 6, 6.8, 3),
+    rect(6.2, 3.6, 2.2, 2.4),
+  ],
+  // An aircraft from above, nose up.
+  airport: [
+    [
+      8, 1.8, 8.9, 2.8, 8.9, 6.6, 14, 9.6, 14, 10.8, 8.9, 9.3, 8.9, 12.3, 10.6,
+      13.6, 10.6, 14.4, 8, 13.7, 5.4, 14.4, 5.4, 13.6, 7.1, 12.3, 7.1, 9.3, 2,
+      10.8, 2, 9.6, 7.1, 6.6, 7.1, 2.8,
+    ],
+  ],
+};
+
+function rect(x: number, y: number, w: number, h: number): number[] {
+  return [x, y, x + w, y, x + w, y + h, x, y + h];
+}
+
+/** The polygon wound clockwise on screen (y down) — positive shoelace
+ *  area — whichever way it was written. */
+function wound(points: readonly number[]): readonly number[] {
+  let area = 0;
+  const n = points.length / 2;
+  for (let i = 0; i < n; i++) {
+    const j = (i + 1) % n;
+    area +=
+      points[i * 2] * points[j * 2 + 1] - points[j * 2] * points[i * 2 + 1];
+  }
+  if (area >= 0) return points;
+  const out: number[] = [];
+  for (let i = n - 1; i >= 0; i--) out.push(points[i * 2], points[i * 2 + 1]);
+  return out;
+}
+
+const WOUND = {} as Record<MapIcon, readonly (readonly number[])[]>;
+for (const name of MAP_ICONS) WOUND[name] = GLYPHS[name].map(wound);
+
+/** Whether `name` is an icon this module draws — a style is data, and may
+ *  come from a file that names one this version does not have. */
+export function isMapIcon(name: unknown): name is MapIcon {
+  return (
+    typeof name === 'string' &&
+    Object.prototype.hasOwnProperty.call(GLYPHS, name)
+  );
+}
+
+/**
+ * Trace a plate `size` across, centred on `cx, cy`: a square with corners
+ * rounded by a fifth of it. Adds to the current path; the caller begins it
+ * and fills it.
+ */
+export function tracePlate(
+  ctx: IconPathContext,
+  cx: number,
+  cy: number,
+  size: number,
+): void {
+  const x = cx - size / 2;
+  const y = cy - size / 2;
+  const r = size * 0.2;
+  const e = size - r;
+  ctx.moveTo(x + r, y);
+  ctx.lineTo(x + e, y);
+  ctx.arc(x + e, y + r, r, -Math.PI / 2, 0);
+  ctx.lineTo(x + size, y + e);
+  ctx.arc(x + e, y + e, r, 0, Math.PI / 2);
+  ctx.lineTo(x + r, y + size);
+  ctx.arc(x + r, y + e, r, Math.PI / 2, Math.PI);
+  ctx.lineTo(x, y + r);
+  ctx.arc(x + r, y + r, r, Math.PI, Math.PI * 1.5);
+  ctx.closePath();
+}
+
+/** Trace `icon`'s glyph over a plate `size` across, centred on `cx, cy`.
+ *  Adds to the current path, as {@link tracePlate} does. */
+export function traceGlyph(
+  ctx: IconPathContext,
+  icon: MapIcon,
+  cx: number,
+  cy: number,
+  size: number,
+): void {
+  const unit = size / GRID;
+  const x = cx - size / 2;
+  const y = cy - size / 2;
+  for (const shape of WOUND[icon]) {
+    ctx.moveTo(x + shape[0] * unit, y + shape[1] * unit);
+    for (let i = 2; i < shape.length; i += 2) {
+      ctx.lineTo(x + shape[i] * unit, y + shape[i + 1] * unit);
+    }
+    ctx.closePath();
+  }
+}

package/src/maps/index.ts

@@ -14,8 +14,9 @@
 // until an application imports the component that needs it, so
 // `sideEffects: false` stays honest. Do not move it into `../index.ts`
 // (AGENTS.md, "Tree-shaking is a constraint").
-import React, { useImperativeHandle, useRef } from 'react';
-import type { ReactElement } from 'react';
+import React, { useEffect, useImperativeHandle, useRef, useState } from 'react';
+import type { ReactElement, ReactNode } from 'react';
+import { useApp, useSupports, useTheme } from 'react-x11';
 import { registerElement, registeredElements } from 'react-x11/host';
 import { createStyles, flattenStyle } from 'react-x11/style';
 // Loads the module the JSX augmentation at the bottom targets: nothing in
@@ -24,16 +25,25 @@ import { createStyles, flattenStyle } from 'react-x11/style';
 // addition. Type-only, so it is erased.
 import type {} from 'react-x11/jsx-runtime';
 
+import { DEFAULT_CAMERA, MapController } from './controller.js';
 import { ELEMENT, MapViewNode, SELF_DAMAGED_PROPS } from './node.js';
+import {
+  chooseRenderer,
+  glRendererModule,
+  loadGlRenderer,
+  rendererFromEnv,
+  rendererRequest,
+} from './renderer.js';
+import type { GlRendererModule } from './renderer.js';
+import { defaultStyleFor, isDarkTheme } from './theme.js';
 import type {
-  FitBoundsOptions,
-  MapCamera,
-  MapHandle,
   MapProps,
+  MapRenderer,
+  MapRendererReason,
   MapViewProps,
 } from './types.js';
-import type { LngLat, LngLatBounds } from './proj.js';
-import type { MapMarker } from './overlay.js';
+
+const h = React.createElement;
 
 if (!registeredElements().includes(ELEMENT)) {
   registerElement(ELEMENT, {
@@ -65,8 +75,6 @@ const styles = createStyles({
   fill: { flexGrow: 1 },
 });
 
-const DEFAULT_CAMERA: MapCamera = { center: { lon: 0, lat: 20 }, zoom: 2 };
-
 /**
  * A map.
  *
@@ -91,87 +99,264 @@ const DEFAULT_CAMERA: MapCamera = { center: { lon: 0, lat: 20 }, zoom: 2 };
  * controlled form, where the application owns where the map is looking.
  */
 export function Map(props: MapProps): ReactElement {
-  const {
-    camera,
-    defaultCamera,
-    onCameraChange,
-    style,
-    children,
-    ref,
-    ...rest
-  } = props;
-
-  const view = useRef<MapViewNode | null>(null);
-  const controlled = camera !== undefined;
-
-  useImperativeHandle(
-    ref,
-    (): MapHandle => ({
-      // Every method reads the node at call time rather than closing over
-      // it: the ref attaches after the commit that created the node, and a
-      // handle built once must still work for the whole mount.
-      getCamera: () => view.current?.getCamera() ?? DEFAULT_CAMERA,
-      setCamera: (next: Partial<MapCamera>) => view.current?.setCamera(next),
-      panBy: (dx: number, dy: number) => view.current?.panBy(dx, dy),
-      zoomIn: (step?: number) => view.current?.zoomIn(step),
-      zoomOut: (step?: number) => view.current?.zoomOut(step),
-      zoomTo: (zoom: number) => view.current?.zoomTo(zoom),
-      fitBounds: (bounds: LngLatBounds, options?: FitBoundsOptions) =>
-        view.current?.fitBounds(bounds, options),
-      fitMarkers: (ids?: readonly string[], options?: FitBoundsOptions) =>
-        view.current?.fitMarkers(ids, options),
-      getBounds: () =>
-        view.current?.getBounds() ?? {
-          west: -180,
-          south: -85,
-          east: 180,
-          north: 85,
-        },
-      project: (position: LngLat) =>
-        view.current?.project(position) ?? { x: 0, y: 0 },
-      unproject: (x: number, y: number) =>
-        view.current?.unproject(x, y) ?? { lon: 0, lat: 0 },
-      markerAt: (x: number, y: number): MapMarker | null =>
-        view.current?.markerAt(x, y) ?? null,
-      refresh: () => view.current?.refresh(),
-      stats: () => view.current?.stats() ?? null,
-    }),
-    [],
+  // One controller for the life of the mount: the camera, the gestures and
+  // the handle, which whichever renderer is drawing answers to (see
+  // `./controller.ts`). Seeded here, once — `defaultCamera` is read on the
+  // first render and never again, which is what makes it a *default*.
+  const [controller] = useState(
+    () => new MapController(props.defaultCamera ?? DEFAULT_CAMERA),
   );
+  // Read at event and frame time, so the latest props are always the ones
+  // that count — and the controlled/uncontrolled fork is simply whether
+  // `camera` is among them.
+  controller.setProps(props);
+  // The controller's own handle, made once: the same object for the whole
+  // mount, whatever draws the map — across a renderer switch too.
+  useImperativeHandle(props.ref, () => controller.handle, [controller]);
+  useEffect(() => () => controller.dispose(), [controller]);
 
-  const flat = flattenStyle(style ?? null);
+  // A GL failure is the map's for the rest of its mount: an `'auto'` map
+  // that met one draws through the retained renderer from then on.
+  const [failure, setFailure] = useState<Error | null>(null);
+  const latest = useRef(props);
+  latest.current = props;
+
+  const flat = flattenStyle(props.style ?? null);
   const sized =
     flat.height !== undefined ||
     flat.flexGrow !== undefined ||
     flat.flexBasis !== undefined;
 
-  // The pane and anything the application puts over it are siblings rather
-  // than parent and children: a registered element's own drawing happens
-  // *after* `super.paint` has painted its children, so anything mounted
-  // inside would be painted over by the map. Beside it, and after it, a
-  // legend or a control panel lands on top. `<Flow>` makes the same
-  // arrangement for the same reason.
-  return React.createElement(
+  const { asked, forced } = rendererRequest(props.renderer, rendererFromEnv());
+  const pane =
+    asked === 'auto'
+      ? h(AutoPane, {
+          key: 'auto',
+          map: props,
+          controller,
+          failed: failure !== null,
+          onFailure: setFailure,
+        })
+      : h(MapPane, {
+          key: asked,
+          renderer: asked,
+          reason: forced ? 'forced' : null,
+          map: props,
+          controller,
+          // Asked for by name: never a fallback, always the application's
+          // to hear about.
+          onFailure: (error: Error) => latest.current.onError?.(error),
+        });
+
+  return h(
     'box',
-    { style: sized ? [styles.clip, style] : [styles.pane, style] },
-    React.createElement(ELEMENT, {
-      ...(rest as MapViewProps),
-      key: 'pane',
-      ref: view,
-      // The controlled/uncontrolled fork, and the whole of it. Controlled:
-      // the application's camera goes down and the element only ever
-      // *asks* to move. Uncontrolled: nothing goes down after the seed, the
-      // element owns the camera, and a pan never reaches React — which is
-      // the difference between a drag that blits a strip and one that
-      // re-renders and re-claims the pane on every pointer step.
-      camera: controlled ? camera : undefined,
-      defaultCamera: controlled ? undefined : (defaultCamera ?? DEFAULT_CAMERA),
-      onCameraChange,
-      style: styles.fill,
-      role: rest.role ?? 'group',
-      'aria-label': rest['aria-label'] ?? 'Map',
+    { style: sized ? [styles.clip, props.style] : [styles.pane, props.style] },
+    pane,
+  );
+}
+
+/** Props `<Map>` reads itself, or that only the GL renderer reads — kept off
+ *  the `<mapview>` element, which would take each as a prop of its own. */
+const NOT_FOR_THE_ELEMENT: readonly string[] = [
+  'camera',
+  'defaultCamera',
+  'style',
+  'children',
+  'ref',
+  'renderer',
+  'onRendererChange',
+  'onError',
+  'levelFade',
+  'adaptive',
+  'buildWorkers',
+  'antialias',
+  'fillRule',
+  'labelsWhileMoving',
+  'onAfterDraw',
+];
+
+function elementProps(map: MapProps): MapViewProps {
+  const out: Record<string, unknown> = { ...map };
+  for (const name of NOT_FOR_THE_ELEMENT) delete out[name];
+  return out as MapViewProps;
+}
+
+interface PaneProps {
+  map: MapProps;
+  controller: MapController;
+  onFailure: (error: Error) => void;
+}
+
+/**
+ * `renderer="auto"`: GL where this connection draws through the direct
+ * backend, the retained renderer everywhere else — `./renderer.ts` is the
+ * decision, and this is where it reads the connection. Its own component so
+ * that a map that asked for a renderer by name never asks the connection: on
+ * the Cocoa backend the question is a GL runtime brought up to answer it.
+ */
+function AutoPane(props: PaneProps & { failed: boolean }): ReactElement {
+  const { map } = props;
+  const app = useApp();
+  const shaders = useSupports('shaders');
+  const probing = useDirectGlProbe(app, shaders);
+  const choice = chooseRenderer({
+    requested: 'auto',
+    shaders,
+    probing,
+    failed: props.failed,
+  });
+  return h(MapPane, {
+    renderer: choice.renderer,
+    reason: choice.reason,
+    map,
+    controller: props.controller,
+    onFailure: props.onFailure,
+  });
+}
+
+/**
+ * Whether this connection's answer to `useSupports('shaders')` is still to
+ * come. Under a policy that could choose direct GL, X11 settles it before
+ * `createRoot()` hands the app back; the Cocoa backend settles it on the
+ * first ask, which is this. Until it has, a map shows its background rather
+ * than drawing through the retained renderer for a few milliseconds and
+ * fetching the view's tiles twice.
+ */
+function useDirectGlProbe(app: unknown, shaders: boolean): boolean {
+  const mode = (app as { glPolicy?: { mode?: string } } | null)?.glPolicy?.mode;
+  const wants = mode === 'auto' || mode === 'direct';
+  const [settled, setSettled] = useState(false);
+  const pending = wants && !shaders && !settled;
+  useEffect(() => {
+    if (!pending) return;
+    const probe = (
+      app as { glCapabilities?(): Promise<unknown> } | null
+    )?.glCapabilities?.();
+    if (!probe) {
+      setSettled(true);
+      return;
+    }
+    let live = true;
+    const done = (): void => {
+      if (live) setSettled(true);
+    };
+    probe.then(done, done);
+    return () => {
+      live = false;
+    };
+  }, [app, pending]);
+  return pending;
+}
+
+/**
+ * The pane, drawn by the renderer chosen: the `<mapview>` element, the GL
+ * renderer once its module has loaded, or — while the connection's answer
+ * or the module is on its way — a box in the style's background. Whichever
+ * it is, it answers to the map's one controller.
+ */
+function MapPane(
+  props: PaneProps & {
+    renderer: MapRenderer | 'pending';
+    reason: MapRendererReason | null;
+  },
+): ReactElement {
+  const { renderer, reason, map, controller } = props;
+  const theme = useTheme();
+  const overlay = useSupports('glOverlay');
+
+  // `onRendererChange`: whenever the map lands somewhere it did not ask for
+  // — its first renderer, or the one it falls back to.
+  const reported = useRef<MapRenderer | null>(null);
+  useEffect(() => {
+    if (renderer === 'pending') return;
+    const before = reported.current;
+    reported.current = renderer;
+    if (before === renderer || reason === null) return;
+    map.onRendererChange?.(renderer, reason);
+  }, [renderer, reason]);
+
+  const wantGl = renderer === 'gl';
+  const [gl, setGl] = useState<GlRendererModule | null>(glRendererModule);
+  useEffect(() => {
+    if (!wantGl || gl) return;
+    let live = true;
+    loadGlRenderer().then(
+      (module) => {
+        if (live) setGl(module);
+      },
+      (error: unknown) => {
+        if (!live) return;
+        props.onFailure(
+          error instanceof Error ? error : new Error(String(error)),
+        );
+      },
+    );
+    return () => {
+      live = false;
+    };
+  }, [wantGl, gl]);
+
+  const common = {
+    style: styles.fill,
+    role: map.role ?? 'group',
+    'aria-label': map['aria-label'] ?? 'Map',
+    'data-testname': map['data-testname'],
+  };
+  // What the application puts over the map is the pane's sibling, after
+  // it, rather than its child: a registered element's own drawing happens
+  // *after* `super.paint` has painted its children, so anything mounted
+  // inside `<mapview>` would be painted over by the map. `<Flow>` makes the
+  // same arrangement for the same reason. The one exception is a GL pane:
+  // a sibling is under its surface, so there they go inside the surface,
+  // whose children core draws above it.
+  const over = (pane: ReactElement, children: ReactNode): ReactElement =>
+    h(React.Fragment, null, pane, children);
+  if (renderer === 'retained') {
+    return over(
+      h(ELEMENT, {
+        ...elementProps(map),
+        ...common,
+        key: 'retained',
+        mapController: controller,
+        // The controlled/uncontrolled fork, and the whole of it.
+        // Controlled: the application's camera goes down and the element
+        // only ever *asks* to move. Uncontrolled: nothing goes down, the
+        // controller owns the camera, and a pan never reaches React —
+        // which is the difference between a drag that blits a strip and
+        // one that re-renders and re-claims the pane on every pointer
+        // step.
+        camera: map.camera,
+      } as MapViewProps),
+      map.children,
+    );
+  }
+  if (renderer === 'gl' && gl) {
+    return over(
+      h(
+        gl.GlMapPane,
+        {
+          ...common,
+          key: 'gl',
+          controller,
+          map,
+          onFailure: props.onFailure,
+        },
+        overlay ? map.children : undefined,
+      ),
+      overlay ? null : map.children,
+    );
+  }
+  const background = (map.mapStyle ?? defaultStyleFor(isDarkTheme(theme)))
+    .background;
+  return over(
+    h('box', {
+      ...common,
+      key: 'pending',
+      style: background
+        ? [styles.fill, { backgroundColor: background }]
+        : styles.fill,
     }),
-    children,
+    map.children,
   );
 }
 
@@ -242,6 +427,8 @@ export {
 
 export { compileFilter, resolveZoomed } from './style.js';
 
+export { MAP_ICONS } from './icons.js';
+
 export {
   decodePolyline,
   geoJsonOverlays,
@@ -256,9 +443,14 @@ export { TileCache } from './tiles.js';
 export type {
   FitBoundsOptions,
   MapFrameStats,
+  MapGlFrameStats,
+  MapGlProps,
   MapHandle,
   MapPointerEvent,
   MapProps,
+  MapRenderer,
+  MapRendererReason,
+  MapRendererRequest,
   MapViewProps,
 } from './types.js';
 export type {
@@ -290,6 +482,7 @@ export type {
   SymbolLayer,
   Zoomed,
 } from './style.js';
+export type { MapIcon } from './icons.js';
 export type {
   MapPalette,
   OpenMapTilesStyleOptions,