@dxos/react-ui-geo 0.8.4-main.fd6878d → 0.8.4-staging.60fe92afc8

package/src/components/Globe/Globe.tsx

@@ -4,6 +4,7 @@
 
 import {
   type GeoProjection,
+  selection as d3Selection,
   easeLinear,
   easeSinOut,
   geoMercator,
@@ -17,7 +18,9 @@ import { type ControlPosition } from 'leaflet';
 import React, {
   type PropsWithChildren,
   forwardRef,
+  useCallback,
   useEffect,
+  useId,
   useImperativeHandle,
   useMemo,
   useRef,
@@ -26,19 +29,32 @@ import React, {
 import { useResizeDetector } from 'react-resize-detector';
 import { type Topology } from 'topojson-specification';
 
-import { type ThemeMode, type ThemedClassName, useDynamicRef, useThemeContext } from '@dxos/react-ui';
-import { mx } from '@dxos/react-ui-theme';
+import {
+  type ThemeMode,
+  type ThemedClassName,
+  useComposedRefs,
+  useControlledState,
+  useDynamicRef,
+  useThemeContext,
+} from '@dxos/react-ui';
+import { composable, composableProps } from '@dxos/react-ui';
+import { mx } from '@dxos/ui-theme';
 
 import {
-  GlobeContextProvider,
-  type GlobeContextProviderProps,
+  GlobeContext,
   type GlobeContextType,
+  type GlobeController,
+  type Point,
+  type Size,
+  type Vector,
   useGlobeContext,
 } from '../../hooks';
 import {
   type Features,
   type StyleSet,
   createLayers,
+  createRotationTween,
+  flyDuration,
   geoToPosition,
   positionToRotation,
   renderLayers,
@@ -54,19 +70,15 @@ const defaultStyles: Record<ThemeMode, StyleSet> = {
     background: {
       fillStyle: '#EEE',
     },
-
     water: {
       fillStyle: '#555',
     },
-
     land: {
       fillStyle: '#999',
     },
-
     line: {
       strokeStyle: 'darkred',
     },
-
     point: {
       fillStyle: '#111111',
       strokeStyle: '#111111',
@@ -78,19 +90,15 @@ const defaultStyles: Record<ThemeMode, StyleSet> = {
     background: {
       fillStyle: '#111111',
     },
-
     water: {
       fillStyle: '#123E6A',
     },
-
     land: {
       fillStyle: '#032153',
     },
-
     line: {
       strokeStyle: '#111111',
     },
-
     point: {
       fillStyle: '#111111',
       strokeStyle: '#111111',
@@ -100,11 +108,6 @@ const defaultStyles: Record<ThemeMode, StyleSet> = {
   },
 };
 
-export type GlobeController = {
-  canvas: HTMLCanvasElement;
-  projection: GeoProjection;
-} & Pick<GlobeContextType, 'zoom' | 'translation' | 'rotation' | 'setZoom' | 'setTranslation' | 'setRotation'>;
-
 export type ProjectionType = 'orthographic' | 'mercator' | 'transverse-mercator';
 
 const projectionMap: Record<ProjectionType, () => GeoProjection> = {
@@ -126,18 +129,96 @@ const getProjection = (type: GlobeCanvasProps['projection'] = 'orthographic'): G
 // Root
 //
 
-type GlobeRootProps = PropsWithChildren<ThemedClassName<GlobeContextProviderProps>>;
+const DEFAULT_ZOOM = 1.5;
 
-const GlobeRoot = ({ classNames, children, ...props }: GlobeRootProps) => {
-  const { ref, width, height } = useResizeDetector<HTMLDivElement>();
-  return (
-    <div ref={ref} className={mx('relative flex grow overflow-hidden', classNames)}>
-      <GlobeContextProvider size={{ width, height }} {...props}>
+type GlobeRootProps = Partial<Pick<GlobeContextType, 'center' | 'zoom' | 'translation' | 'rotation'>> &
+  PropsWithChildren;
+
+/**
+ * Headless context/state provider for the globe. Renders no DOM; wrap a `Globe.Viewport` to mount
+ * the measured container. The current `GlobeController` (built by `Globe.Canvas`) is exposed via
+ * this component's `ref`.
+ */
+const GlobeRoot = forwardRef<GlobeController | null, GlobeRootProps>(
+  (
+    {
+      children,
+      center: centerProp,
+      zoom: zoomProp = DEFAULT_ZOOM,
+      translation: translationProp,
+      rotation: rotationProp,
+    },
+    forwardedRef,
+  ) => {
+    const [size, setSize] = useState<Size>({ width: 0, height: 0 });
+    const [center, setCenter] = useControlledState(centerProp);
+    const [zoom, setZoom] = useControlledState(zoomProp);
+    const [translation, setTranslation] = useControlledState<Point>(translationProp);
+    const [rotation, setRotation] = useControlledState<Vector>(rotationProp);
+
+    // The controller is built by Globe.Canvas and registered here; Globe.Root re-exposes it via its
+    // ref. Held in state (not a ref) so that when Globe.Canvas registers a new controller, Root
+    // re-renders and the imperative handle below updates — re-running consumer effects keyed on the
+    // controller (e.g. useDrag/useWheel) once the canvas mounts.
+    const [controller, setController] = useState<GlobeController | null>(null);
+    const registerController = useCallback((next: GlobeController | null) => setController(next), []);
+
+    // Expose the live controller (or null until Globe.Canvas mounts) via Root's ref.
+    useImperativeHandle(forwardedRef, () => controller, [controller]);
+
+    return (
+      <GlobeContext.Provider
+        value={{
+          size,
+          center,
+          zoom,
+          translation,
+          rotation,
+          setSize,
+          setCenter,
+          setZoom,
+          setTranslation,
+          setRotation,
+          registerController,
+        }}
+      >
         {children}
-      </GlobeContextProvider>
+      </GlobeContext.Provider>
+    );
+  },
+);
+
+GlobeRoot.displayName = 'Globe.Root';
+
+//
+// Viewport
+//
+
+/** Consumer-facing props for `Globe.Viewport` (classNames + children). */
+type GlobeViewportProps = ThemedClassName<PropsWithChildren>;
+
+/**
+ * Measured container for the globe. Renders the `relative dx-container` div, observes its size, and
+ * publishes measurements to the context so `Globe.Canvas` can size the canvas.
+ */
+const GlobeViewport = composable<HTMLDivElement>(({ children, ...props }, forwardedRef) => {
+  const { setSize } = useGlobeContext();
+  const localRef = useRef<HTMLDivElement>(null);
+  const composedRef = useComposedRefs<HTMLDivElement>(localRef, forwardedRef);
+  const { width, height } = useResizeDetector<HTMLDivElement>({ targetRef: localRef });
+
+  useEffect(() => {
+    setSize({ width: width ?? 0, height: height ?? 0 });
+  }, [width, height, setSize]);
+
+  return (
+    <div {...composableProps(props, { classNames: 'relative dx-container' })} ref={composedRef}>
+      {children}
     </div>
   );
-};
+});
+
+GlobeViewport.displayName = 'Globe.Viewport';
 
 //
 // Canvas
@@ -151,103 +232,165 @@ type GlobeCanvasProps = {
 };
 
 /**
- * Basic globe renderer.
+ * Basic globe renderer. Builds the imperative `GlobeController` and registers it with `Globe.Root`
+ * (via `registerController` from context) so consumers reading the controller from Root's ref get
+ * the live instance.
  * https://github.com/topojson/world-atlas
  */
-// TODO(burdon): Move controller to root.
-const GlobeCanvas = forwardRef<GlobeController, GlobeCanvasProps>(
-  ({ projection: _projection, topology, features, styles: _styles }, forwardRef) => {
-    const { themeMode } = useThemeContext();
-    const styles = useMemo(() => _styles ?? defaultStyles[themeMode], [_styles, themeMode]);
-
-    // Canvas.
-    const [canvas, setCanvas] = useState<HTMLCanvasElement>(null);
-    const canvasRef = (canvas: HTMLCanvasElement) => setCanvas(canvas);
-
-    // Projection.
-    const projection = useMemo(() => getProjection(_projection), [_projection]);
-
-    // Layers.
-    // TODO(burdon): Generate on the fly based on what is visible.
-    const layers = useMemo(() => {
-      return timer(() => createLayers(topology as Topology, features, styles));
-    }, [topology, features, styles]);
-
-    // State.
-    const { size, center, zoom, translation, rotation, setCenter, setZoom, setTranslation, setRotation } =
-      useGlobeContext();
-    const zoomRef = useDynamicRef(zoom);
-
-    // Update rotation.
-    useEffect(() => {
-      if (center) {
-        setZoom(1);
-        setRotation(positionToRotation(geoToPosition(center)));
-      }
-    }, [center]);
-
-    // External controller.
-    const zooming = useRef(false);
-    useImperativeHandle<GlobeController, GlobeController>(forwardRef, () => {
-      return {
-        canvas,
-        projection,
-        center,
-        get zoom() {
-          return zoomRef.current;
-        },
-        translation,
-        rotation,
-        setCenter,
-        setZoom: (s) => {
-          if (typeof s === 'function') {
-            const is = interpolateNumber(zoomRef.current, s(zoomRef.current));
-            // Stop easing if already zooming.
-            transition()
-              .ease(zooming.current ? easeLinear : easeSinOut)
-              .duration(200)
-              .tween('scale', () => (t) => setZoom(is(t)))
-              .on('end', () => {
-                zooming.current = false;
-              });
-          } else {
-            setZoom(s);
-          }
-        },
-        setTranslation,
-        setRotation,
-      };
-    }, [canvas]);
-
-    // https://d3js.org/d3-geo/path#geoPath
-    // https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext
-    const generator = useMemo(
-      () => canvas && projection && geoPath(projection, canvas.getContext('2d', { alpha: false })),
-      [canvas, projection],
-    );
+const GlobeCanvas = ({ projection: projectionProp, topology, features, styles: stylesProp }: GlobeCanvasProps) => {
+  const { themeMode } = useThemeContext();
+  const styles = useMemo(() => stylesProp ?? defaultStyles[themeMode], [stylesProp, themeMode]);
+  const { size, center, zoom, translation, rotation, setZoom, setTranslation, setRotation, registerController } =
+    useGlobeContext();
+
+  const zoomRef = useDynamicRef(zoom);
+
+  // Canvas.
+  const [canvas, setCanvas] = useState<HTMLCanvasElement>(null);
+  const canvasRef = (canvas: HTMLCanvasElement) => setCanvas(canvas);
+
+  // Projection.
+  const projection = useMemo(() => getProjection(projectionProp), [projectionProp]);
+
+  // Layers.
+  // TODO(burdon): Generate on-the-fly based on what is visible.
+  const layers = useMemo(() => {
+    return timer(() => createLayers(topology as Topology, features, styles));
+  }, [topology, features, styles]);
+
+  // Update rotation when the center changes. Preserve current zoom — callers can set zoom
+  // independently via the `zoom` prop or `setZoom` on the controller.
+  useEffect(() => {
+    if (center) {
+      setRotation(positionToRotation(geoToPosition(center)));
+    }
+  }, [center]);
+
+  // Per-instance flyTo plumbing. d3 named transitions are scoped per DOM
+  // element and `d3Selection()` returns the documentElement root, so a
+  // shared name would let one globe's flyTo interrupt another's. The
+  // useId-scoped name keeps each Globe.Canvas's transition isolated.
+  const flyToSelection = useMemo(() => d3Selection(), []);
+  const flyToTransitionName = `globe-fly-to-${useId()}`;
+  useEffect(
+    () => () => {
+      flyToSelection.interrupt(flyToTransitionName);
+    },
+    [flyToSelection, flyToTransitionName],
+  );
 
-    // Render on change.
-    useEffect(() => {
-      if (canvas && projection) {
-        timer(() => {
-          // https://d3js.org/d3-geo/projection
-          projection
-            .scale((Math.min(size.width, size.height) / 2) * zoom)
-            .translate([size.width / 2 + (translation?.x ?? 0), size.height / 2 + (translation?.y ?? 0)])
-            .rotate(rotation ?? [0, 0, 0]);
-
-          renderLayers(generator, layers, zoom, styles);
-        });
-      }
-    }, [generator, size, zoom, translation, rotation, layers]);
-
-    if (!size.width || !size.height) {
-      return null;
+  // External controller.
+  const zooming = useRef(false);
+  const controller = useMemo<GlobeController>(() => {
+    return {
+      canvas,
+      projection,
+      get zoom() {
+        return zoomRef.current;
+      },
+      translation,
+      rotation,
+      setZoom: (state) => {
+        if (typeof state === 'function') {
+          const is = interpolateNumber(zoomRef.current, state(zoomRef.current));
+          // Stop easing if already zooming.
+          transition()
+            .ease(zooming.current ? easeLinear : easeSinOut)
+            .duration(200)
+            .tween('scale', () => (t) => setZoom(is(t)))
+            .on('end', () => {
+              zooming.current = false;
+            });
+        } else {
+          setZoom(state);
+        }
+      },
+      setTranslation,
+      setRotation,
+      flyTo: (target, options = {}) => {
+        const { duration = 1_200, tilt = 0, onTick } = options;
+        const p2 = geoToPosition(target);
+        const r1 = projection.rotate() as Vector;
+        const r2 = positionToRotation(p2, tilt);
+
+        // Approximate current centre from the inverse of the rotation.
+        const p1: [number, number] = [-r1[0], -r1[1]];
+        const rotationTween = createRotationTween(projection, setRotation, r1, r2);
+        const iz = target.zoom !== undefined ? interpolateNumber(zoomRef.current, target.zoom) : undefined;
+
+        flyToSelection.interrupt(flyToTransitionName);
+        const tx = flyToSelection.transition(flyToTransitionName).duration(flyDuration(p1, p2, duration, 1_500));
+        if (onTick) {
+          tx.tween('flyToOnTick', () => onTick);
+        }
+        tx.tween('flyToRotation', () => rotationTween);
+        if (iz) {
+          tx.tween('flyToZoom', () => (t: number) => setZoom(iz(t)));
+        }
+        return tx.end();
+      },
+      cancelFlyTo: () => {
+        flyToSelection.interrupt(flyToTransitionName);
+      },
+    };
+    // Keep the controller IDENTITY stable: only rebuild on these mount-stable deps. Deliberately
+    // exclude `center`/`translation`/`rotation` — they are read here as closure snapshots, and
+    // callers pass them as inline literals (e.g. `rotation={[0, 0, 0]}`), so a fresh reference every
+    // render would rebuild the controller, re-fire `registerController`, re-render Root, hand a new
+    // controller back through the consumer's `ref={setController}`, and loop forever. `projection`
+    // must stay in deps: switching between stories that pass different projection types creates a new
+    // instance via useMemo, and any consumer reading controller.projection (e.g. useDrag) would
+    // otherwise mutate a dead instance while the canvas renders the new one. The `useControlledState`
+    // setters and `zoomRef` are stable, so they need not be listed.
+  }, [canvas, projection, flyToSelection, flyToTransitionName]);
+
+  // Register the controller with Globe.Root and clear it on unmount.
+  useEffect(() => {
+    registerController(controller);
+    return () => registerController(null);
+  }, [registerController, controller]);
+
+  // https://d3js.org/d3-geo/path#geoPath
+  // https://developer.mozilla.org/en-US/docs/Web/API/HTMLCanvasElement/getContext
+  // Keep the context alpha-enabled: when a style set omits `background`, `renderLayers`
+  // clears to transparent so the canvas's themed CSS background (below) shows through the
+  // area outside the globe — correct in both light and dark mode.
+  const generator = useMemo(
+    () => canvas && projection && geoPath(projection, canvas.getContext('2d')),
+    [canvas, projection],
+  );
+
+  // Render on change.
+  useEffect(() => {
+    if (canvas && projection) {
+      timer(() => {
+        // https://d3js.org/d3-geo/projection
+        projection
+          .scale((Math.min(size.width, size.height) / 2) * zoom)
+          .translate([size.width / 2 + (translation?.x ?? 0), size.height / 2 + (translation?.y ?? 0)])
+          .rotate(rotation ?? [0, 0, 0]);
+
+        // Provide a view-center for per-frame culling — only meaningful for
+        // projections that present a single visible hemisphere (e.g.
+        // orthographic). For Mercator/transverse-mercator the whole sphere
+        // is always visible, so we skip culling.
+        const isOrthographic = !projectionProp || projectionProp === 'orthographic';
+        const [lambda, phi] = (rotation ?? [0, 0, 0]) as Vector;
+        const viewCenter: [number, number] | undefined = isOrthographic ? [-lambda, -phi] : undefined;
+
+        renderLayers(generator, layers, zoom, styles, viewCenter);
+      });
     }
+  }, [generator, size, zoom, translation, rotation, layers, projectionProp]);
 
-    return <canvas ref={canvasRef} width={size.width} height={size.height} />;
-  },
-);
+  if (!size.width || !size.height) {
+    return null;
+  }
+
+  return <canvas ref={canvasRef} className='bg-base-surface' width={size.width} height={size.height} />;
+};
+
+GlobeCanvas.displayName = 'Globe.Canvas';
 
 //
 // Debug
@@ -258,7 +401,7 @@ const GlobeDebug = ({ position = 'topleft' }: { position?: ControlPosition }) =>
   return (
     <div
       className={mx(
-        'z-10 absolute w-96 p-2 overflow-hidden border border-green-700 rounded',
+        'z-10 absolute w-96 p-2 overflow-hidden border border-green-700 rounded-sm',
         controlPositions[position],
       )}
     >
@@ -309,6 +452,7 @@ const GlobeAction = ({ onAction, position = 'bottomright', ...props }: GlobeCont
 
 export const Globe = {
   Root: GlobeRoot,
+  Viewport: GlobeViewport,
   Canvas: GlobeCanvas,
   Zoom: GlobeZoom,
   Action: GlobeAction,
@@ -316,4 +460,4 @@ export const Globe = {
   Panel: GlobePanel,
 };
 
-export type { GlobeRootProps, GlobeCanvasProps };
+export type { GlobeRootProps, GlobeViewportProps, GlobeCanvasProps };

package/src/components/Map/Map.stories.tsx

@@ -2,45 +2,85 @@
 // Copyright 2024 DXOS.org
 //
 
-import '@dxos-theme';
-
 import { type Meta, type StoryObj } from '@storybook/react-vite';
-import React, { useState } from 'react';
+import React, { useMemo, useState } from 'react';
 
-import { withLayout, withTheme } from '@dxos/storybook-utils';
+import { Input, Panel, Toolbar } from '@dxos/react-ui';
+import { withLayout, withTheme } from '@dxos/react-ui/testing';
 
 import { useMapZoomHandler } from '../../hooks';
 import { type GeoMarker } from '../../types';
+import { Map, MapMarkersProps, MapTilesProps, type MapController } from './Map';
 
-import { Map, type MapController } from './Map';
+type DefaultStoryProps = Pick<MapTilesProps, 'url'> & Pick<MapMarkersProps, 'markers'>;
 
-const DefaultStory = ({ markers = [] }: { markers?: GeoMarker[] }) => {
+const DefaultStory = ({ url: urlProp, markers = [] }: DefaultStoryProps) => {
   const [controller, setController] = useState<MapController>();
+  const [key, setKey] = useState('');
+  // Substitute the `${key}` placeholder in a keyed tile URL (e.g. MapTiler); undefined → default OSM tiles.
+  const url = useMemo(() => urlProp?.replace('${key}', key), [urlProp, key]);
+
   const handleZoomAction = useMapZoomHandler(controller);
 
   return (
-    <Map.Root ref={setController}>
-      <Map.Tiles />
-      <Map.Markers markers={markers} />
-      <Map.Zoom position='bottomleft' onAction={handleZoomAction} />
-      <Map.Action position='bottomright' />
-    </Map.Root>
+    <Panel.Root>
+      {urlProp && (
+        <Panel.Toolbar asChild>
+          <Toolbar.Root>
+            <Input.Root>
+              <Input.TextInput
+                spellCheck={false}
+                placeholder='API KEY'
+                value={key}
+                onChange={(ev) => setKey(ev.target.value)}
+              />
+            </Input.Root>
+          </Toolbar.Root>
+        </Panel.Toolbar>
+      )}
+      {/* Map.Root is headless (context only), so it sits outside Panel.Content; Panel.Content asChild
+          then targets the Leaflet frame (Map.Viewport) directly — no extra wrapper element. */}
+      <Map.Root ref={setController}>
+        <Panel.Content asChild>
+          <Map.Viewport>
+            <Map.Tiles url={url} />
+            <Map.Markers markers={markers} />
+            <Map.Zoom position='bottomleft' onAction={handleZoomAction} />
+            <Map.Action position='bottomright' />
+          </Map.Viewport>
+        </Panel.Content>
+      </Map.Root>
+    </Panel.Root>
   );
 };
 
-const meta: Meta<typeof DefaultStory> = {
+const meta = {
   title: 'ui/react-ui-geo/Map',
+  component: Map.Root as any,
   render: DefaultStory,
-  decorators: [withTheme, withLayout({ fullscreen: true })],
-};
+  decorators: [withTheme(), withLayout({ layout: 'fullscreen' })],
+  parameters: {
+    layout: 'fullscreen',
+  },
+} satisfies Meta<typeof DefaultStory>;
 
 export default meta;
 
-type Story = StoryObj<typeof DefaultStory>;
+type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {};
 
-export const WithMarkers: Story = {
+export const Bounds: Story = {
+  args: {
+    markers: [
+      { id: 'london', title: 'London', location: { lat: 51.5074, lng: -0.1278 } },
+      { id: 'barcelona', title: 'Barcelona', location: { lat: 41.3851, lng: 2.1734 } },
+      { id: 'warsaw', title: 'Warsaw', location: { lat: 52.2297, lng: 21.0122 } },
+    ] as GeoMarker[],
+  },
+};
+
+export const Markers: Story = {
   args: {
     markers: [
       { id: 'los angeles', title: 'Los Angeles', location: { lat: 34.0522, lng: -118.2437 } },
@@ -68,3 +108,12 @@ export const WithMarkers: Story = {
     ] as GeoMarker[],
   },
 };
+
+/**
+ * https://docs.maptiler.com/leaflet
+ */
+export const CustomTiles: Story = {
+  args: {
+    url: 'https://api.maptiler.com/maps/streets-v4/{z}/{x}/{y}.png?&key=${key}',
+  },
+};