@elabs-ai/components-maps 4.0.0

package/src/map-cluster-layer/map-cluster-layer.tsx

@@ -0,0 +1,292 @@
+"use client";
+
+import type MapLibreGL from "maplibre-gl";
+import { useEffect, useId, useMemo } from "react";
+
+import { useMap } from "../map-canvas/map-context";
+import { useTokenColor } from "../lib/use-token-color";
+
+export type MapClusterLayerProps<P extends GeoJSON.GeoJsonProperties = GeoJSON.GeoJsonProperties> =
+  {
+    /** GeoJSON FeatureCollection data or a URL to fetch GeoJSON from. */
+    data: string | GeoJSON.FeatureCollection<GeoJSON.Point, P>;
+    /** Maximum zoom level to cluster points on (default: 14). */
+    clusterMaxZoom?: number;
+    /** Radius of each cluster when clustering points, in pixels (default: 50). */
+    clusterRadius?: number;
+    /**
+     * Colors for cluster circles: [small, medium, large] based on point count.
+     * Defaults to the theme's `--success`/`--warning`/`--destructive` tokens.
+     */
+    clusterColors?: [string, string, string];
+    /** Point-count thresholds for the color/size steps: [medium, large] (default: [100, 750]). */
+    clusterThresholds?: [number, number];
+    /** Color for unclustered individual points. Defaults to the theme's `--primary` token. */
+    pointColor?: string;
+    /** Callback when an unclustered point is clicked. */
+    onPointClick?: (
+      feature: GeoJSON.Feature<GeoJSON.Point, P>,
+      coordinates: [number, number],
+    ) => void;
+    /** Callback when a cluster is clicked. If not provided, zooms into the cluster. */
+    onClusterClick?: (clusterId: number, coordinates: [number, number], pointCount: number) => void;
+  };
+
+const DEFAULT_CLUSTER_THRESHOLDS: [number, number] = [100, 750];
+
+/**
+ * Clustered point rendering for large point datasets. Cluster circles step
+ * through the status tokens (success → warning → destructive) as the point
+ * count grows; strokes and count labels use the page surface for contrast.
+ */
+export function MapClusterLayer<P extends GeoJSON.GeoJsonProperties = GeoJSON.GeoJsonProperties>({
+  data,
+  clusterMaxZoom = 14,
+  clusterRadius = 50,
+  clusterColors,
+  clusterThresholds = DEFAULT_CLUSTER_THRESHOLDS,
+  pointColor,
+  onPointClick,
+  onClusterClick,
+}: MapClusterLayerProps<P>) {
+  const { map, isLoaded } = useMap();
+  const id = useId();
+  const sourceId = `cluster-source-${id}`;
+  const clusterLayerId = `clusters-${id}`;
+  const clusterCountLayerId = `cluster-count-${id}`;
+  const unclusteredLayerId = `unclustered-point-${id}`;
+
+  const success = useTokenColor("--success");
+  const warning = useTokenColor("--warning");
+  const destructive = useTokenColor("--destructive");
+  const primary = useTokenColor("--primary");
+  const surface = useTokenColor("--background");
+
+  const resolvedClusterColors = useMemo<[string, string, string]>(
+    () => clusterColors ?? [success, warning, destructive],
+    [clusterColors, success, warning, destructive],
+  );
+  const resolvedPointColor = pointColor ?? primary;
+
+  // Add source and layers on mount.
+  useEffect(() => {
+    if (!isLoaded || !map) return;
+
+    map.addSource(sourceId, {
+      type: "geojson",
+      data,
+      cluster: true,
+      clusterMaxZoom,
+      clusterRadius,
+    });
+
+    map.addLayer({
+      id: clusterLayerId,
+      type: "circle",
+      source: sourceId,
+      filter: ["has", "point_count"],
+      paint: {
+        "circle-color": [
+          "step",
+          ["get", "point_count"],
+          resolvedClusterColors[0],
+          clusterThresholds[0],
+          resolvedClusterColors[1],
+          clusterThresholds[1],
+          resolvedClusterColors[2],
+        ],
+        "circle-radius": [
+          "step",
+          ["get", "point_count"],
+          20,
+          clusterThresholds[0],
+          30,
+          clusterThresholds[1],
+          40,
+        ],
+        "circle-stroke-width": 1,
+        "circle-stroke-color": surface,
+        "circle-opacity": 0.85,
+      },
+    });
+
+    map.addLayer({
+      id: clusterCountLayerId,
+      type: "symbol",
+      source: sourceId,
+      filter: ["has", "point_count"],
+      layout: {
+        "text-field": "{point_count_abbreviated}",
+        "text-font": ["Open Sans"],
+        "text-size": 12,
+      },
+      paint: {
+        "text-color": surface,
+      },
+    });
+
+    map.addLayer({
+      id: unclusteredLayerId,
+      type: "circle",
+      source: sourceId,
+      filter: ["!", ["has", "point_count"]],
+      paint: {
+        "circle-color": resolvedPointColor,
+        "circle-radius": 5,
+        "circle-stroke-width": 2,
+        "circle-stroke-color": surface,
+      },
+    });
+
+    return () => {
+      try {
+        if (map.getLayer(clusterCountLayerId)) map.removeLayer(clusterCountLayerId);
+        if (map.getLayer(unclusteredLayerId)) map.removeLayer(unclusteredLayerId);
+        if (map.getLayer(clusterLayerId)) map.removeLayer(clusterLayerId);
+        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, sourceId]);
+
+  // Update source data when the data prop changes (only for non-URL data).
+  useEffect(() => {
+    if (!isLoaded || !map || typeof data === "string") return;
+
+    const source = map.getSource(sourceId) as MapLibreGL.GeoJSONSource;
+    if (source) {
+      source.setData(data);
+    }
+  }, [isLoaded, map, data, sourceId]);
+
+  // Sync layer styles when props (or the resolved theme colors) change.
+  useEffect(() => {
+    if (!isLoaded || !map) return;
+
+    if (map.getLayer(clusterLayerId)) {
+      map.setPaintProperty(clusterLayerId, "circle-color", [
+        "step",
+        ["get", "point_count"],
+        resolvedClusterColors[0],
+        clusterThresholds[0],
+        resolvedClusterColors[1],
+        clusterThresholds[1],
+        resolvedClusterColors[2],
+      ]);
+      map.setPaintProperty(clusterLayerId, "circle-radius", [
+        "step",
+        ["get", "point_count"],
+        20,
+        clusterThresholds[0],
+        30,
+        clusterThresholds[1],
+        40,
+      ]);
+      map.setPaintProperty(clusterLayerId, "circle-stroke-color", surface);
+    }
+
+    if (map.getLayer(clusterCountLayerId)) {
+      map.setPaintProperty(clusterCountLayerId, "text-color", surface);
+    }
+
+    if (map.getLayer(unclusteredLayerId)) {
+      map.setPaintProperty(unclusteredLayerId, "circle-color", resolvedPointColor);
+      map.setPaintProperty(unclusteredLayerId, "circle-stroke-color", surface);
+    }
+  }, [
+    isLoaded,
+    map,
+    clusterLayerId,
+    clusterCountLayerId,
+    unclusteredLayerId,
+    resolvedClusterColors,
+    clusterThresholds,
+    resolvedPointColor,
+    surface,
+  ]);
+
+  // Handle click events.
+  useEffect(() => {
+    if (!isLoaded || !map) return;
+
+    // Cluster click handler — zoom into the cluster by default.
+    const handleClusterClick = async (e: MapLibreGL.MapMouseEvent) => {
+      const features = map.queryRenderedFeatures(e.point, {
+        layers: [clusterLayerId],
+      });
+      const feature = features[0];
+      if (!feature) return;
+      const clusterId = feature.properties?.cluster_id as number;
+      const pointCount = feature.properties?.point_count as number;
+      const coordinates = (feature.geometry as GeoJSON.Point).coordinates as [number, number];
+
+      if (onClusterClick) {
+        onClusterClick(clusterId, coordinates, pointCount);
+      } else {
+        const source = map.getSource(sourceId) as MapLibreGL.GeoJSONSource;
+        const zoom = await source.getClusterExpansionZoom(clusterId);
+        map.easeTo({
+          center: coordinates,
+          zoom,
+        });
+      }
+    };
+
+    // Unclustered point click handler.
+    const handlePointClick = (
+      e: MapLibreGL.MapMouseEvent & {
+        features?: MapLibreGL.MapGeoJSONFeature[];
+      },
+    ) => {
+      const feature = e.features?.[0];
+      if (!onPointClick || !feature) return;
+      const coordinates = (feature.geometry as GeoJSON.Point).coordinates.slice() as [
+        number,
+        number,
+      ];
+
+      // Handle world copies.
+      while (Math.abs(e.lngLat.lng - coordinates[0]) > 180) {
+        coordinates[0] += e.lngLat.lng > coordinates[0] ? 360 : -360;
+      }
+
+      onPointClick(feature as unknown as GeoJSON.Feature<GeoJSON.Point, P>, coordinates);
+    };
+
+    // Cursor style handlers.
+    const handleMouseEnterCluster = () => {
+      map.getCanvas().style.cursor = "pointer";
+    };
+    const handleMouseLeaveCluster = () => {
+      map.getCanvas().style.cursor = "";
+    };
+    const handleMouseEnterPoint = () => {
+      if (onPointClick) {
+        map.getCanvas().style.cursor = "pointer";
+      }
+    };
+    const handleMouseLeavePoint = () => {
+      map.getCanvas().style.cursor = "";
+    };
+
+    map.on("click", clusterLayerId, handleClusterClick);
+    map.on("click", unclusteredLayerId, handlePointClick);
+    map.on("mouseenter", clusterLayerId, handleMouseEnterCluster);
+    map.on("mouseleave", clusterLayerId, handleMouseLeaveCluster);
+    map.on("mouseenter", unclusteredLayerId, handleMouseEnterPoint);
+    map.on("mouseleave", unclusteredLayerId, handleMouseLeavePoint);
+
+    return () => {
+      map.off("click", clusterLayerId, handleClusterClick);
+      map.off("click", unclusteredLayerId, handlePointClick);
+      map.off("mouseenter", clusterLayerId, handleMouseEnterCluster);
+      map.off("mouseleave", clusterLayerId, handleMouseLeaveCluster);
+      map.off("mouseenter", unclusteredLayerId, handleMouseEnterPoint);
+      map.off("mouseleave", unclusteredLayerId, handleMouseLeavePoint);
+    };
+  }, [isLoaded, map, clusterLayerId, unclusteredLayerId, sourceId, onClusterClick, onPointClick]);
+
+  return null;
+}

package/src/map-controls/index.ts

@@ -0,0 +1 @@
+export { MapControls, type MapControlsProps } from "./map-controls";

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

@@ -0,0 +1,43 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { MapCanvas } from "../map-canvas";
+import { MapControls } from "./map-controls";
+
+const meta = {
+  title: "Maps/MapControls",
+  component: MapControls,
+  tags: ["autodocs"],
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof MapControls>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  render: () => (
+    <div className="h-[480px]">
+      <MapCanvas center={[2.3522, 48.8566]} zoom={11}>
+        <MapControls />
+      </MapCanvas>
+    </div>
+  ),
+};
+
+export const AllControls: Story = {
+  render: () => (
+    <div className="h-[480px]">
+      <MapCanvas center={[2.3522, 48.8566]} zoom={11} pitch={30} bearing={-20}>
+        <MapControls showZoom showCompass showLocate showFullscreen />
+      </MapCanvas>
+    </div>
+  ),
+};
+
+export const TopLeft: Story = {
+  render: () => (
+    <div className="h-[480px]">
+      <MapCanvas center={[2.3522, 48.8566]} zoom={11}>
+        <MapControls position="top-left" showCompass />
+      </MapCanvas>
+    </div>
+  ),
+};

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

@@ -0,0 +1,56 @@
+import { cleanup, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+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 { MapControls } from "./map-controls";
+
+afterEach(() => {
+  cleanup();
+  resetMaplibreMock();
+});
+
+describe("MapControls", () => {
+  it("renders zoom buttons by default with accessible names", async () => {
+    render(
+      <MapCanvas>
+        <MapControls />
+      </MapCanvas>,
+    );
+    expect(await screen.findByRole("button", { name: "Zoom in" })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Zoom out" })).toBeInTheDocument();
+    expect(
+      screen.queryByRole("button", { name: "Reset bearing to north" }),
+    ).not.toBeInTheDocument();
+  });
+
+  it("renders compass, locate and fullscreen controls when enabled", async () => {
+    render(
+      <MapCanvas>
+        <MapControls showCompass showLocate showFullscreen />
+      </MapCanvas>,
+    );
+    expect(
+      await screen.findByRole("button", { name: "Reset bearing to north" }),
+    ).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Find my location" })).toBeInTheDocument();
+    expect(screen.getByRole("button", { name: "Toggle fullscreen" })).toBeInTheDocument();
+  });
+
+  it("zooms the map when zoom in is clicked", async () => {
+    const user = userEvent.setup();
+    render(
+      <MapCanvas>
+        <MapControls />
+      </MapCanvas>,
+    );
+    await user.click(await screen.findByRole("button", { name: "Zoom in" }));
+    expect(MockMap.instances[0]!.zoomToCalls.length).toBeGreaterThan(0);
+  });
+});

package/src/map-controls/map-controls.tsx

@@ -0,0 +1,220 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState, type ReactNode } from "react";
+import { Locate, Maximize, Minus, Plus } from "lucide-react";
+import { Spinner } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+
+import { useMap } from "../map-canvas/map-context";
+
+export interface MapControlsProps {
+  /** Position of the controls on the map (default: "bottom-right"). */
+  position?: "top-left" | "top-right" | "bottom-left" | "bottom-right";
+  /** Show zoom in/out buttons (default: true). */
+  showZoom?: boolean;
+  /** Show a compass button to reset bearing/pitch (default: false). */
+  showCompass?: boolean;
+  /** Show a locate button to fly to the user's location (default: false). */
+  showLocate?: boolean;
+  /** Show a fullscreen toggle button (default: false). */
+  showFullscreen?: boolean;
+  /** Additional CSS classes for the controls container. */
+  className?: string;
+  /** Callback with user coordinates when located. */
+  onLocate?: (coords: { longitude: number; latitude: number }) => void;
+  /** Callback when geolocation fails or is denied. */
+  onLocateError?: (error: GeolocationPositionError) => void;
+}
+
+// bottom-right sits above MapLibre's attribution control — keep it visible.
+const positionClasses = {
+  "top-left": "top-2 left-2",
+  "top-right": "top-2 right-2",
+  "bottom-left": "bottom-2 left-2",
+  "bottom-right": "bottom-10 right-2",
+};
+
+function ControlGroup({ children }: { children: ReactNode }) {
+  return (
+    <div className="flex flex-col divide-y overflow-hidden rounded-md bg-surface-elevated shadow-ring-sm">
+      {children}
+    </div>
+  );
+}
+
+function ControlButton({
+  onClick,
+  label,
+  children,
+  disabled = false,
+}: {
+  onClick: () => void;
+  label: string;
+  children: ReactNode;
+  disabled?: boolean;
+}) {
+  return (
+    <button
+      onClick={onClick}
+      aria-label={label}
+      type="button"
+      className={cn(
+        "flex size-8 items-center justify-center text-foreground transition-colors duration-fast",
+        "hover:bg-surface-muted",
+        "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring",
+        "disabled:pointer-events-none disabled:opacity-50",
+      )}
+      disabled={disabled}
+    >
+      {children}
+    </button>
+  );
+}
+
+/** Branded zoom / compass / locate / fullscreen controls. Render inside `<MapCanvas>`. */
+export function MapControls({
+  position = "bottom-right",
+  showZoom = true,
+  showCompass = false,
+  showLocate = false,
+  showFullscreen = false,
+  className,
+  onLocate,
+  onLocateError,
+}: MapControlsProps) {
+  const { map } = useMap();
+  const [waitingForLocation, setWaitingForLocation] = useState(false);
+
+  const handleZoomIn = useCallback(() => {
+    map?.zoomTo(map.getZoom() + 1, { duration: 300 });
+  }, [map]);
+
+  const handleZoomOut = useCallback(() => {
+    map?.zoomTo(map.getZoom() - 1, { duration: 300 });
+  }, [map]);
+
+  const handleResetBearing = useCallback(() => {
+    map?.resetNorthPitch({ duration: 300 });
+  }, [map]);
+
+  const handleLocate = useCallback(() => {
+    if (!("geolocation" in navigator)) return;
+    setWaitingForLocation(true);
+    navigator.geolocation.getCurrentPosition(
+      (pos) => {
+        const coords = {
+          longitude: pos.coords.longitude,
+          latitude: pos.coords.latitude,
+        };
+        map?.flyTo({
+          center: [coords.longitude, coords.latitude],
+          zoom: 14,
+          duration: 1500,
+        });
+        onLocate?.(coords);
+        setWaitingForLocation(false);
+      },
+      (error) => {
+        onLocateError?.(error);
+        setWaitingForLocation(false);
+      },
+    );
+  }, [map, onLocate, onLocateError]);
+
+  const handleFullscreen = useCallback(() => {
+    const container = map?.getContainer();
+    if (!container) return;
+    if (document.fullscreenElement) {
+      void document.exitFullscreen();
+    } else {
+      void container.requestFullscreen();
+    }
+  }, [map]);
+
+  return (
+    <div
+      className={cn("absolute z-10 flex flex-col gap-1.5", positionClasses[position], className)}
+    >
+      {showZoom && (
+        <ControlGroup>
+          <ControlButton onClick={handleZoomIn} label="Zoom in">
+            <Plus className="size-4" aria-hidden="true" />
+          </ControlButton>
+          <ControlButton onClick={handleZoomOut} label="Zoom out">
+            <Minus className="size-4" aria-hidden="true" />
+          </ControlButton>
+        </ControlGroup>
+      )}
+      {showCompass && (
+        <ControlGroup>
+          <CompassButton onClick={handleResetBearing} />
+        </ControlGroup>
+      )}
+      {showLocate && (
+        <ControlGroup>
+          <ControlButton
+            onClick={handleLocate}
+            label="Find my location"
+            disabled={waitingForLocation}
+          >
+            {waitingForLocation ? (
+              <Spinner label="Locating" className="size-4 text-foreground" />
+            ) : (
+              <Locate className="size-4" aria-hidden="true" />
+            )}
+          </ControlButton>
+        </ControlGroup>
+      )}
+      {showFullscreen && (
+        <ControlGroup>
+          <ControlButton onClick={handleFullscreen} label="Toggle fullscreen">
+            <Maximize className="size-4" aria-hidden="true" />
+          </ControlButton>
+        </ControlGroup>
+      )}
+    </div>
+  );
+}
+
+function CompassButton({ onClick }: { onClick: () => void }) {
+  const { map } = useMap();
+  const compassRef = useRef<SVGSVGElement>(null);
+
+  useEffect(() => {
+    if (!map || !compassRef.current) return;
+
+    const compass = compassRef.current;
+
+    const updateRotation = () => {
+      const bearing = map.getBearing();
+      const pitch = map.getPitch();
+      compass.style.transform = `rotateX(${pitch}deg) rotateZ(${-bearing}deg)`;
+    };
+
+    map.on("rotate", updateRotation);
+    map.on("pitch", updateRotation);
+    updateRotation();
+
+    return () => {
+      map.off("rotate", updateRotation);
+      map.off("pitch", updateRotation);
+    };
+  }, [map]);
+
+  return (
+    <ControlButton onClick={onClick} label="Reset bearing to north">
+      <svg
+        ref={compassRef}
+        viewBox="0 0 24 24"
+        aria-hidden="true"
+        className="size-5 transition-transform duration-fast"
+        style={{ transformStyle: "preserve-3d" }}
+      >
+        <path d="M12 2L16 12H12V2Z" className="fill-destructive" />
+        <path d="M12 2L8 12H12V2Z" className="fill-destructive/50" />
+        <path d="M12 22L16 12H12V22Z" className="fill-muted-foreground/60" />
+        <path d="M12 22L8 12H12V22Z" className="fill-muted-foreground/30" />
+      </svg>
+    </ControlButton>
+  );
+}

package/src/map-geojson/index.ts

@@ -0,0 +1,9 @@
+export {
+  MapGeoJSON,
+  type MapGeoJSONProps,
+  type MapGeoJSONData,
+  type MapGeoJSONEvent,
+  type MapGeoJSONFeature,
+  type MapFillPaint,
+  type MapLinePaint,
+} from "./map-geojson";