@elabs-ai/components-maps 4.0.0

package/src/map-arc/map-arc.tsx

@@ -0,0 +1,294 @@
+"use client";
+
+import type MapLibreGL from "maplibre-gl";
+import { useEffect, useId, useMemo, useRef } from "react";
+
+import { useMap } from "../map-canvas/map-context";
+import { buildArcCoordinates } from "../lib/arc-math";
+import { mergeHoverPaint } from "../lib/merge-hover-paint";
+import { useTokenColor } from "../lib/use-token-color";
+
+/** A single arc to render inside `<MapArc data={...}>`. */
+export type MapArcDatum = {
+  /** Unique identifier for this arc. Required for hover state tracking and event payloads. */
+  id: string | number;
+  /** Start coordinate as [longitude, latitude]. */
+  from: [number, number];
+  /** End coordinate as [longitude, latitude]. */
+  to: [number, number];
+};
+
+/** Event payload passed to MapArc interaction callbacks. */
+export type MapArcEvent<T extends MapArcDatum = MapArcDatum> = {
+  /** The arc datum that was hovered or clicked. */
+  arc: T;
+  /** Longitude of the cursor at the time of the event. */
+  longitude: number;
+  /** Latitude of the cursor at the time of the event. */
+  latitude: number;
+  /** The underlying MapLibre mouse event for advanced use cases. */
+  originalEvent: MapLibreGL.MapMouseEvent;
+};
+
+export type MapArcLinePaint = NonNullable<MapLibreGL.LineLayerSpecification["paint"]>;
+export type MapArcLineLayout = NonNullable<MapLibreGL.LineLayerSpecification["layout"]>;
+
+export type MapArcProps<T extends MapArcDatum = MapArcDatum> = {
+  /** Array of arcs to render. Each arc must have a unique `id`. */
+  data: T[];
+  /** Optional unique identifier prefix for the arc source/layers. Auto-generated if not provided. */
+  id?: string;
+  /**
+   * How far each arc bows away from a straight line. `0` renders straight
+   * lines; higher values bend further; negative values bend to the opposite
+   * side. Arcs cross the antimeridian via the shorter direction. (default: 0.2)
+   */
+  curvature?: number;
+  /** Number of samples used to render each curve. Higher = smoother. (default: 64) */
+  samples?: number;
+  /**
+   * MapLibre paint properties for the arc layer. Merged on top of theme-aware
+   * defaults (`line-color` = the `--primary` token, `line-width: 2`,
+   * `line-opacity: 0.85`). Any value can be a MapLibre expression for
+   * per-feature styling; every field on each arc datum (besides `from`/`to`)
+   * is exposed via `["get", ...]`.
+   */
+  paint?: MapArcLinePaint;
+  /** MapLibre layout properties for the arc layer. Defaults to rounded joins/caps. */
+  layout?: MapArcLineLayout;
+  /**
+   * Paint properties applied to the arc currently under the cursor. Each key
+   * is merged into `paint` as a `case` expression keyed on per-feature hover
+   * state, so only the hovered arc changes appearance.
+   */
+  hoverPaint?: MapArcLinePaint;
+  /** Callback when an arc is clicked. */
+  onClick?: (e: MapArcEvent<T>) => void;
+  /**
+   * Callback fired when the hovered arc changes. Receives the cursor's
+   * lng/lat at the moment of entry, and `null` when the cursor leaves the
+   * last hovered arc.
+   */
+  onHover?: (e: MapArcEvent<T> | null) => void;
+  /** Whether arcs respond to mouse events (default: true). */
+  interactive?: boolean;
+  /** Optional MapLibre layer id to insert the arc layers before (z-order control). */
+  beforeId?: string;
+};
+
+const DEFAULT_ARC_CURVATURE = 0.2;
+const DEFAULT_ARC_SAMPLES = 64;
+const ARC_HIT_MIN_WIDTH = 12;
+const ARC_HIT_PADDING = 6;
+
+const DEFAULT_ARC_LAYOUT: MapArcLineLayout = {
+  "line-join": "round",
+  "line-cap": "round",
+};
+
+/**
+ * Curved great-circle-style arcs between coordinate pairs (flight paths,
+ * network links). Pairs well with `<MapCanvas blank projection={{ type: "globe" }}>`.
+ */
+export function MapArc<T extends MapArcDatum = MapArcDatum>({
+  data,
+  id: propId,
+  curvature = DEFAULT_ARC_CURVATURE,
+  samples = DEFAULT_ARC_SAMPLES,
+  paint,
+  layout,
+  hoverPaint,
+  onClick,
+  onHover,
+  interactive = true,
+  beforeId,
+}: MapArcProps<T>) {
+  const { map, isLoaded } = useMap();
+  const autoId = useId();
+  const id = propId ?? autoId;
+  const sourceId = `arc-source-${id}`;
+  const layerId = `arc-layer-${id}`;
+  const hitLayerId = `arc-hit-layer-${id}`;
+
+  const primary = useTokenColor("--primary");
+
+  const mergedPaint = useMemo(
+    () =>
+      mergeHoverPaint(
+        { "line-color": primary, "line-width": 2, "line-opacity": 0.85, ...paint },
+        hoverPaint,
+      ),
+    [primary, paint, hoverPaint],
+  );
+  const mergedLayout = useMemo(() => ({ ...DEFAULT_ARC_LAYOUT, ...layout }), [layout]);
+
+  const hitWidth = useMemo(() => {
+    const w = paint?.["line-width"] ?? 2;
+    const base = typeof w === "number" ? w : ARC_HIT_MIN_WIDTH;
+    return Math.max(base + ARC_HIT_PADDING, ARC_HIT_MIN_WIDTH);
+  }, [paint]);
+
+  const geoJSON = useMemo<GeoJSON.FeatureCollection<GeoJSON.LineString>>(
+    () => ({
+      type: "FeatureCollection",
+      features: data.map((arc) => {
+        const { from, to, ...properties } = arc;
+        return {
+          type: "Feature",
+          properties,
+          geometry: {
+            type: "LineString",
+            coordinates: buildArcCoordinates(from, to, curvature, samples),
+          },
+        };
+      }),
+    }),
+    [data, curvature, samples],
+  );
+
+  const latestRef = useRef({ data, onClick, onHover });
+  latestRef.current = { data, onClick, onHover };
+
+  // Add source and layers on mount. The invisible hit layer widens the
+  // pointer target so thin arcs stay hoverable/clickable.
+  useEffect(() => {
+    if (!isLoaded || !map) return;
+
+    map.addSource(sourceId, {
+      type: "geojson",
+      data: geoJSON,
+      promoteId: "id",
+    });
+
+    map.addLayer(
+      {
+        id: hitLayerId,
+        type: "line",
+        source: sourceId,
+        layout: DEFAULT_ARC_LAYOUT,
+        paint: {
+          "line-color": "transparent",
+          "line-width": hitWidth,
+          "line-opacity": 1,
+        },
+      },
+      beforeId,
+    );
+
+    map.addLayer(
+      {
+        id: layerId,
+        type: "line",
+        source: sourceId,
+        layout: mergedLayout,
+        paint: mergedPaint,
+      },
+      beforeId,
+    );
+
+    return () => {
+      try {
+        if (map.getLayer(layerId)) map.removeLayer(layerId);
+        if (map.getLayer(hitLayerId)) map.removeLayer(hitLayerId);
+        if (map.getSource(sourceId)) map.removeSource(sourceId);
+      } catch {
+        // style may be mid-reload
+      }
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- source/layers created once per map; data + paint are synced by the effects below
+  }, [isLoaded, map]);
+
+  // Sync features when data / curvature / samples change.
+  useEffect(() => {
+    if (!isLoaded || !map) return;
+    const source = map.getSource(sourceId) as MapLibreGL.GeoJSONSource | undefined;
+    source?.setData(geoJSON);
+  }, [isLoaded, map, geoJSON, sourceId]);
+
+  // Sync paint/layout when they change.
+  useEffect(() => {
+    if (!isLoaded || !map || !map.getLayer(layerId)) return;
+    for (const [key, value] of Object.entries(mergedPaint)) {
+      map.setPaintProperty(layerId, key as keyof MapArcLinePaint, value as never);
+    }
+    for (const [key, value] of Object.entries(mergedLayout)) {
+      map.setLayoutProperty(layerId, key as keyof MapArcLineLayout, value as never);
+    }
+    if (map.getLayer(hitLayerId)) {
+      map.setPaintProperty(hitLayerId, "line-width", hitWidth);
+    }
+  }, [isLoaded, map, layerId, hitLayerId, mergedPaint, mergedLayout, hitWidth]);
+
+  // Interaction handlers (bound to the hit layer).
+  useEffect(() => {
+    if (!isLoaded || !map || !interactive) return;
+
+    let hoveredId: string | number | null = null;
+
+    const setHover = (next: string | number | null) => {
+      if (next === hoveredId) return;
+      const sourceExists = !!map.getSource(sourceId);
+      if (hoveredId != null && sourceExists) {
+        map.setFeatureState({ source: sourceId, id: hoveredId }, { hover: false });
+      }
+      hoveredId = next;
+      if (next != null && sourceExists) {
+        map.setFeatureState({ source: sourceId, id: next }, { hover: true });
+      }
+    };
+
+    const findArc = (featureId: string | number | undefined) =>
+      featureId == null
+        ? undefined
+        : latestRef.current.data.find((arc) => String(arc.id) === String(featureId));
+
+    const handleMouseMove = (e: MapLibreGL.MapLayerMouseEvent) => {
+      const featureId = e.features?.[0]?.id as string | number | undefined;
+      if (featureId == null || featureId === hoveredId) return;
+
+      setHover(featureId);
+      map.getCanvas().style.cursor = "pointer";
+
+      const arc = findArc(featureId);
+      if (arc) {
+        latestRef.current.onHover?.({
+          arc: arc as T,
+          longitude: e.lngLat.lng,
+          latitude: e.lngLat.lat,
+          originalEvent: e,
+        });
+      }
+    };
+
+    const handleMouseLeave = () => {
+      setHover(null);
+      map.getCanvas().style.cursor = "";
+      latestRef.current.onHover?.(null);
+    };
+
+    const handleClick = (e: MapLibreGL.MapLayerMouseEvent) => {
+      const arc = findArc(e.features?.[0]?.id as string | number | undefined);
+      if (!arc) return;
+      latestRef.current.onClick?.({
+        arc: arc as T,
+        longitude: e.lngLat.lng,
+        latitude: e.lngLat.lat,
+        originalEvent: e,
+      });
+    };
+
+    map.on("mousemove", hitLayerId, handleMouseMove);
+    map.on("mouseleave", hitLayerId, handleMouseLeave);
+    map.on("click", hitLayerId, handleClick);
+
+    return () => {
+      map.off("mousemove", hitLayerId, handleMouseMove);
+      map.off("mouseleave", hitLayerId, handleMouseLeave);
+      map.off("click", hitLayerId, handleClick);
+      setHover(null);
+      map.getCanvas().style.cursor = "";
+    };
+  }, [isLoaded, map, hitLayerId, sourceId, interactive]);
+
+  return null;
+}

package/src/map-canvas/index.ts

@@ -0,0 +1,8 @@
+export {
+  MapCanvas,
+  type MapCanvasProps,
+  type MapCanvasRef,
+  type MapViewport,
+  type MapStyleOption,
+} from "./map-canvas";
+export { useMap, type MapContextValue, type BasemapTheme } from "./map-context";

package/src/map-canvas/map-canvas-webgl-fallback.test.tsx

@@ -0,0 +1,30 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+// MapLibre throws at construction when WebGL is unavailable — the canvas must
+// degrade to a quiet panel, not an unhandled render error (smoke-test contract).
+vi.mock("maplibre-gl", () => {
+  class ThrowingMap {
+    constructor() {
+      throw new Error("Failed to initialize WebGL");
+    }
+  }
+  return { default: { Map: ThrowingMap }, Map: ThrowingMap };
+});
+
+import { MapCanvas } from "./map-canvas";
+
+afterEach(cleanup);
+
+describe("MapCanvas without WebGL", () => {
+  it("renders the unavailable panel instead of throwing", () => {
+    render(
+      <MapCanvas className="my-map">
+        <div data-testid="child" />
+      </MapCanvas>,
+    );
+    expect(screen.getByText("Map unavailable")).toBeInTheDocument();
+    // Children (which need the map context) are not rendered in this state.
+    expect(screen.queryByTestId("child")).not.toBeInTheDocument();
+  });
+});

package/src/map-canvas/map-canvas.stories.tsx

@@ -0,0 +1,54 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { MapCanvas } from "./map-canvas";
+import { MapControls } from "../map-controls";
+
+const meta = {
+  title: "Maps/MapCanvas",
+  component: MapCanvas,
+  tags: ["autodocs"],
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof MapCanvas>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <div className="h-[480px]">
+      <MapCanvas center={[13.405, 52.52]} zoom={11}>
+        <MapControls />
+      </MapCanvas>
+    </div>
+  ),
+};
+
+/** The `loading` prop shows an accessible overlay while the app fetches map data. */
+export const Loading: Story = {
+  render: () => (
+    <div className="h-[480px]">
+      <MapCanvas center={[13.405, 52.52]} zoom={11} loading />
+    </div>
+  ),
+};
+
+/** Pin the basemap flavor regardless of the active brand theme. */
+export const ForcedDarkBasemap: Story = {
+  render: () => (
+    <div className="h-[480px]">
+      <MapCanvas center={[-74.006, 40.7128]} zoom={10} theme="dark">
+        <MapControls />
+      </MapCanvas>
+    </div>
+  ),
+};
+
+/** A globe projection — pairs well with `blank` + data layers for data-viz. */
+export const Globe: Story = {
+  render: () => (
+    <div className="h-[480px]">
+      <MapCanvas center={[10, 30]} zoom={1.5} projection={{ type: "globe" }}>
+        <MapControls showCompass />
+      </MapCanvas>
+    </div>
+  ),
+};

package/src/map-canvas/map-canvas.test.tsx

@@ -0,0 +1,93 @@
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+// maplibre-gl requires WebGL — mock the engine and assert the brand wrapper's
+// own output. Real rendering + a11y are covered by Storybook story tests.
+vi.mock("maplibre-gl", async () => {
+  const { createMaplibreMock } = await import("../test-utils/maplibre-mock");
+  return createMaplibreMock();
+});
+
+import { MockMap, resetMaplibreMock } from "../test-utils/maplibre-mock";
+import { MapCanvas } from "./map-canvas";
+import { useMap } from "./map-context";
+
+afterEach(() => {
+  cleanup();
+  resetMaplibreMock();
+});
+
+describe("MapCanvas", () => {
+  it("renders the container and applies custom className", () => {
+    const { container } = render(<MapCanvas className="my-map" />);
+    expect(container.firstChild).toHaveClass("my-map");
+  });
+
+  it("creates a MapLibre map on mount and removes it on unmount", () => {
+    const { unmount } = render(<MapCanvas />);
+    expect(MockMap.instances).toHaveLength(1);
+    unmount();
+    expect(MockMap.instances[0]!.removed).toBe(true);
+  });
+
+  // A deliberate maintainer default for internal use — see
+  // .claude/rules/map-components.md. The rule carries the constraint that the
+  // Carto/OSM basemap legally requires the credit for PUBLIC surfaces; these two
+  // tests exist so the default can't be flipped, or the override broken, silently.
+  it("disables the MapLibre attribution control by default", () => {
+    render(<MapCanvas />);
+    expect(MockMap.instances[0]!.options.attributionControl).toBe(false);
+  });
+
+  it("lets a consumer re-enable the attribution control for a public surface", () => {
+    render(<MapCanvas attributionControl={{ compact: true }} />);
+    expect(MockMap.instances[0]!.options.attributionControl).toEqual({ compact: true });
+  });
+
+  it("renders children once the map instance exists", async () => {
+    render(
+      <MapCanvas>
+        <div data-testid="child">child</div>
+      </MapCanvas>,
+    );
+    expect(await screen.findByTestId("child")).toBeInTheDocument();
+  });
+
+  it("shows an accessible loading overlay while loading", () => {
+    render(<MapCanvas loading />);
+    expect(screen.getByRole("status", { name: "Loading map" })).toBeInTheDocument();
+  });
+
+  it("hides the loading overlay once loaded and not loading", async () => {
+    render(<MapCanvas loading={false} />);
+    // The mock fires "load" synchronously, so the overlay must be gone.
+    await waitFor(() => {
+      expect(screen.queryByRole("status")).not.toBeInTheDocument();
+    });
+  });
+
+  it("exposes the map instance through context", async () => {
+    let seen: unknown = null;
+    function Probe() {
+      const { map } = useMap();
+      seen = map;
+      return null;
+    }
+    render(
+      <MapCanvas>
+        <Probe />
+      </MapCanvas>,
+    );
+    await waitFor(() => {
+      expect(seen).toBe(MockMap.instances[0]);
+    });
+  });
+
+  it("useMap throws outside of MapCanvas", () => {
+    function Bare() {
+      useMap();
+      return null;
+    }
+    expect(() => render(<Bare />)).toThrow(/within a <MapCanvas>/);
+  });
+});