@react-x11/components 0.8.0 → 0.9.0

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,263 @@ 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]);
+
+  // 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(style ?? null);
+  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',
+  '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,
   );
 }
 
@@ -256,9 +440,14 @@ export { TileCache } from './tiles.js';
 export type {
   FitBoundsOptions,
   MapFrameStats,
+  MapGlFrameStats,
+  MapGlProps,
   MapHandle,
   MapPointerEvent,
   MapProps,
+  MapRenderer,
+  MapRendererReason,
+  MapRendererRequest,
   MapViewProps,
 } from './types.js';
 export type {