@elabs-ai/components-maps 4.0.0

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

@@ -0,0 +1,349 @@
+"use client";
+
+import MapLibreGL from "maplibre-gl";
+import "maplibre-gl/dist/maplibre-gl.css";
+import "./maps.css";
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
+import { Spinner, StatePanel } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+
+import { MapContext, type BasemapTheme } from "./map-context";
+import { useResolvedBasemapTheme } from "./use-resolved-basemap-theme";
+
+/**
+ * Default basemaps: Carto's free light/dark GL styles. These serve ODbL-licensed
+ * OpenStreetMap data, which requires attribution on a public surface — see the
+ * `attributionControl` note in the map constructor below.
+ */
+const defaultStyles = {
+  dark: "https://basemaps.cartocdn.com/gl/dark-matter-gl-style/style.json",
+  light: "https://basemaps.cartocdn.com/gl/positron-gl-style/style.json",
+};
+
+// A tile-less, dependency-free style with a transparent background. Use it for
+// data visualizations (choropleths, arcs, dot maps) where you draw your own
+// layers and don't need a street basemap: `<MapCanvas blank>`. The transparent
+// background lets the themed container show through.
+const blankMapStyle: MapLibreGL.StyleSpecification = {
+  version: 8,
+  sources: {},
+  layers: [
+    {
+      id: "background",
+      type: "background",
+      paint: { "background-color": "transparent" },
+    },
+  ],
+};
+
+/** Map viewport state. */
+export interface MapViewport {
+  /** Center coordinates [longitude, latitude]. */
+  center: [number, number];
+  /** Zoom level. */
+  zoom: number;
+  /** Bearing (rotation) in degrees. */
+  bearing: number;
+  /** Pitch (tilt) in degrees. */
+  pitch: number;
+}
+
+export type MapStyleOption = string | MapLibreGL.StyleSpecification;
+
+/** The imperative handle exposed by `<MapCanvas ref>`: the MapLibre map itself. */
+export type MapCanvasRef = MapLibreGL.Map;
+
+export type MapCanvasProps = {
+  children?: ReactNode;
+  /** Additional CSS classes for the map container. */
+  className?: string;
+  /**
+   * Basemap flavor. If not provided, it is derived from the active brand theme
+   * (`data-theme` + that theme's own `color-scheme`), then a `dark`/`light` root class,
+   * then the OS preference.
+   */
+  theme?: BasemapTheme;
+  /** Custom map styles for light and dark themes. Overrides the default Carto styles. */
+  styles?: {
+    light?: MapStyleOption;
+    dark?: MapStyleOption;
+  };
+  /**
+   * Use a transparent, tile-less basemap instead of the default Carto street
+   * basemap — a blank canvas. Used alone it renders nothing; add your own
+   * layers on top (`<MapGeoJSON>`, `<MapArc>`, markers, …). Ideal for data
+   * visualizations. Ignored when an explicit `styles` prop is provided.
+   */
+  blank?: boolean;
+  /** Map projection type. Use `{ type: "globe" }` for a 3D globe view. */
+  projection?: MapLibreGL.ProjectionSpecification;
+  /**
+   * Controlled viewport. When provided together with `onViewportChange`, the
+   * map becomes controlled and the viewport is driven by this prop.
+   */
+  viewport?: Partial<MapViewport>;
+  /**
+   * Callback fired continuously as the viewport changes (pan, zoom, rotate,
+   * pitch). Use standalone to observe changes, or with `viewport` for
+   * controlled mode.
+   */
+  onViewportChange?: (viewport: MapViewport) => void;
+  /** Show a loading overlay on the map (e.g. while the app fetches map data). */
+  loading?: boolean;
+} & Omit<MapLibreGL.MapOptions, "container" | "style">;
+
+function MapLoadingOverlay() {
+  return (
+    <div className="absolute inset-0 z-10 flex items-center justify-center bg-background/50 backdrop-blur-xs">
+      <Spinner label="Loading map" className="size-5" />
+    </div>
+  );
+}
+
+function getViewport(map: MapLibreGL.Map): MapViewport {
+  const center = map.getCenter();
+  return {
+    center: [center.lng, center.lat],
+    zoom: map.getZoom(),
+    bearing: map.getBearing(),
+    pitch: map.getPitch(),
+  };
+}
+
+/**
+ * The root map surface — a token/theme-aware MapLibre GL canvas. Compose the
+ * other `@elabs-ai/components-maps` components (markers, popups, controls, layers) as
+ * children; they reach the map through context (`useMap`).
+ *
+ * The ref exposes the raw MapLibre `Map` instance for imperative work
+ * (`flyTo`, `fitBounds`, …).
+ */
+export const MapCanvas = forwardRef<MapCanvasRef, MapCanvasProps>(function MapCanvas(
+  {
+    children,
+    className,
+    theme: themeProp,
+    styles,
+    blank = false,
+    projection,
+    viewport,
+    onViewportChange,
+    loading = false,
+    ...props
+  },
+  ref,
+) {
+  const containerRef = useRef<HTMLDivElement>(null);
+  const [mapInstance, setMapInstance] = useState<MapLibreGL.Map | null>(null);
+  const [initFailed, setInitFailed] = useState(false);
+  const [isLoaded, setIsLoaded] = useState(false);
+  const [isStyleLoaded, setIsStyleLoaded] = useState(false);
+  const currentStyleRef = useRef<MapStyleOption | null>(null);
+  const styleTimeoutRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const internalUpdateRef = useRef(false);
+  const { resolvedTheme, themeKey } = useResolvedBasemapTheme(themeProp);
+
+  const isControlled = viewport !== undefined && onViewportChange !== undefined;
+
+  const onViewportChangeRef = useRef(onViewportChange);
+  onViewportChangeRef.current = onViewportChange;
+
+  const mapStyles = useMemo(() => {
+    // Explicit styles win. Otherwise `blank` opts into the transparent
+    // tile-less basemap; with neither, fall back to the Carto defaults.
+    if (styles) {
+      return {
+        dark: styles.dark ?? defaultStyles.dark,
+        light: styles.light ?? defaultStyles.light,
+      };
+    }
+    if (blank) {
+      return { dark: blankMapStyle, light: blankMapStyle };
+    }
+    return defaultStyles;
+  }, [styles, blank]);
+
+  // Expose the map instance to the parent component.
+  useImperativeHandle(ref, () => mapInstance as MapLibreGL.Map, [mapInstance]);
+
+  const clearStyleTimeout = useCallback(() => {
+    if (styleTimeoutRef.current) {
+      clearTimeout(styleTimeoutRef.current);
+      styleTimeoutRef.current = null;
+    }
+  }, []);
+
+  // Initialize the map.
+  useEffect(() => {
+    if (!containerRef.current) return;
+
+    const initialStyle = resolvedTheme === "dark" ? mapStyles.dark : mapStyles.light;
+    currentStyleRef.current = initialStyle;
+
+    let map: MapLibreGL.Map;
+    try {
+      map = new MapLibreGL.Map({
+        container: containerRef.current,
+        style: initialStyle,
+        renderWorldCopies: false,
+        // Attribution control OFF by default — a maintainer decision for internal
+        // use, taken deliberately and recorded in CHANGELOG.md + the map-components
+        // rule. NOTE THE CONSTRAINT: the default Carto basemap serves OpenStreetMap
+        // data, which is ODbL-licensed and requires the credit, and Carto's terms
+        // require it too — so a surface that ships PUBLICLY on these tiles must turn
+        // it back on with `attributionControl={{ compact: true }}` (it wins through
+        // `...props` below), or move to tiles licensed without the requirement via
+        // `styles` / `blank`.
+        attributionControl: false,
+        ...props,
+        ...viewport,
+      });
+    } catch {
+      // MapLibre throws at construction when WebGL is unavailable (headless
+      // browsers without GPU, remote desktops). Degrade to a quiet panel
+      // instead of an unhandled render error.
+      setInitFailed(true);
+      return;
+    }
+
+    const styleDataHandler = () => {
+      clearStyleTimeout();
+      // Delay so the style is fully processed before layer operations — avoids
+      // race conditions on setStyle without force-updating every layer.
+      styleTimeoutRef.current = setTimeout(() => {
+        setIsStyleLoaded(true);
+        if (projection) {
+          map.setProjection(projection);
+        }
+      }, 100);
+    };
+    // No-op under the default (`attributionControl: false` above). This exists for
+    // the case a consumer turns the control back ON for a public surface: MapLibre
+    // paints even a COMPACT control expanded on first render (`<details open>` +
+    // `maplibregl-compact-show`), so the credits land as a text slab until someone
+    // clicks the toggle. Collapse it to the labelled ⓘ button instead.
+    const loadHandler = () => {
+      setIsLoaded(true);
+      map
+        .getContainer()
+        .querySelectorAll<HTMLDetailsElement>("details.maplibregl-ctrl-attrib[open]")
+        .forEach((el) => {
+          el.open = false;
+        });
+    };
+
+    // Viewport change handler — skip if triggered by an internal update.
+    const handleMove = () => {
+      if (internalUpdateRef.current) return;
+      onViewportChangeRef.current?.(getViewport(map));
+    };
+
+    map.on("load", loadHandler);
+    map.on("styledata", styleDataHandler);
+    map.on("move", handleMove);
+    setMapInstance(map);
+
+    return () => {
+      clearStyleTimeout();
+      map.off("load", loadHandler);
+      map.off("styledata", styleDataHandler);
+      map.off("move", handleMove);
+      map.remove();
+      setIsLoaded(false);
+      setIsStyleLoaded(false);
+      setMapInstance(null);
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- mount-only: map options are init-time; style/theme/projection changes are synced by the effects below
+  }, []);
+
+  // Sync controlled viewport to the map.
+  useEffect(() => {
+    if (!mapInstance || !isControlled || !viewport) return;
+    if (mapInstance.isMoving()) return;
+
+    const current = getViewport(mapInstance);
+    const next = {
+      center: viewport.center ?? current.center,
+      zoom: viewport.zoom ?? current.zoom,
+      bearing: viewport.bearing ?? current.bearing,
+      pitch: viewport.pitch ?? current.pitch,
+    };
+
+    if (
+      next.center[0] === current.center[0] &&
+      next.center[1] === current.center[1] &&
+      next.zoom === current.zoom &&
+      next.bearing === current.bearing &&
+      next.pitch === current.pitch
+    ) {
+      return;
+    }
+
+    internalUpdateRef.current = true;
+    mapInstance.jumpTo(next);
+    internalUpdateRef.current = false;
+  }, [mapInstance, isControlled, viewport]);
+
+  // Swap the basemap style when the theme flips.
+  useEffect(() => {
+    if (!mapInstance || !resolvedTheme) return;
+
+    const newStyle = resolvedTheme === "dark" ? mapStyles.dark : mapStyles.light;
+
+    if (currentStyleRef.current === newStyle) return;
+
+    clearStyleTimeout();
+    currentStyleRef.current = newStyle;
+    setIsStyleLoaded(false);
+
+    mapInstance.setStyle(newStyle, { diff: true });
+  }, [mapInstance, resolvedTheme, mapStyles, clearStyleTimeout]);
+
+  // Sync projection when the prop changes after mount.
+  useEffect(() => {
+    if (!mapInstance || !isStyleLoaded || !projection) return;
+    mapInstance.setProjection(projection);
+  }, [mapInstance, isStyleLoaded, projection]);
+
+  const contextValue = useMemo(
+    () => ({
+      map: mapInstance,
+      isLoaded: isLoaded && isStyleLoaded,
+      resolvedTheme,
+      themeKey,
+    }),
+    [mapInstance, isLoaded, isStyleLoaded, resolvedTheme, themeKey],
+  );
+
+  if (initFailed) {
+    return (
+      <div className={cn("relative h-full w-full", className)}>
+        <StatePanel
+          kind="error"
+          title="Map unavailable"
+          description="This browser can’t render WebGL maps."
+          className="h-full"
+        />
+      </div>
+    );
+  }
+
+  return (
+    <MapContext.Provider value={contextValue}>
+      <div ref={containerRef} className={cn("relative h-full w-full", className)}>
+        {(!isLoaded || loading) && <MapLoadingOverlay />}
+        {/* SSR-safe: children render only when the map exists on the client. */}
+        {mapInstance && children}
+      </div>
+    </MapContext.Provider>
+  );
+});

package/src/map-canvas/map-context.ts

@@ -0,0 +1,32 @@
+"use client";
+
+import type MapLibreGL from "maplibre-gl";
+import { createContext, use } from "react";
+
+/** Light-or-dark flavor of the active basemap (derived from the brand theme). */
+export type BasemapTheme = "light" | "dark";
+
+export interface MapContextValue {
+  /** The live MapLibre map instance (`null` until the map has mounted). */
+  map: MapLibreGL.Map | null;
+  /** True once the map AND its style are fully loaded — gate layer operations on this. */
+  isLoaded: boolean;
+  /** Which basemap flavor is active. */
+  resolvedTheme: BasemapTheme;
+  /**
+   * Changes whenever the active brand theme changes. Layer components use it
+   * as a dependency key to re-resolve semantic token colors for WebGL paint.
+   */
+  themeKey: string;
+}
+
+export const MapContext = createContext<MapContextValue | null>(null);
+
+/** Access the map instance + load state from any descendant of `<MapCanvas>`. */
+export function useMap(): MapContextValue {
+  const context = use(MapContext);
+  if (!context) {
+    throw new Error("useMap must be used within a <MapCanvas>");
+  }
+  return context;
+}

package/src/map-canvas/maps.css

@@ -0,0 +1,15 @@
+/*
+ * MapLibre popup chrome reset — @elabs-ai/components-maps popups paint their own surface
+ * (bg-popover, border, shadow), so MapLibre's white bubble + tip must not
+ * render underneath. Imported by <MapCanvas> alongside maplibre-gl's CSS.
+ */
+.maplibregl-popup-content {
+  background: transparent;
+  box-shadow: none;
+  padding: 0;
+  border-radius: 0;
+}
+
+.maplibregl-popup-tip {
+  display: none;
+}

package/src/map-canvas/use-resolved-basemap-theme.ts

@@ -0,0 +1,77 @@
+"use client";
+
+import { resolveThemeIsDark } from "@elabs-ai/components-tokens";
+import { useEffect, useState } from "react";
+
+import type { BasemapTheme } from "./map-context";
+
+/**
+ * Brand theme → basemap flavor. When a `data-theme` is set (the ThemeProvider
+ * contract) the theme's own `color-scheme` is authoritative via
+ * `resolveThemeIsDark` — which is why a CONSUMER-AUTHORED dark theme gets the
+ * dark basemap without registering anything here (ADR 0029; the old
+ * `THEME_META[theme].dark` lookup only knew the themes this repo ships). A
+ * `dark`/`light` class on `<html>` is honored for non-brand hosts (next-themes
+ * et al.); the OS preference is only the last-resort fallback.
+ */
+function getBrandTheme(): BasemapTheme | null {
+  if (typeof document === "undefined") return null;
+  const root = document.documentElement;
+  if (root.getAttribute("data-theme")) return resolveThemeIsDark(root) ? "dark" : "light";
+  if (root.classList.contains("dark")) return "dark";
+  if (root.classList.contains("light")) return "light";
+  return null;
+}
+
+function getSystemTheme(): BasemapTheme {
+  if (typeof window === "undefined" || typeof window.matchMedia !== "function") return "light";
+  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+
+function getThemeAttribute(): string {
+  if (typeof document === "undefined") return "";
+  return document.documentElement.getAttribute("data-theme") ?? "";
+}
+
+/**
+ * Resolve the basemap flavor and a change-key for the active brand theme.
+ * The observer stays active even with an explicit `theme` prop: token colors
+ * (routes, clusters, …) must still re-resolve when `data-theme` changes.
+ */
+export function useResolvedBasemapTheme(themeProp?: BasemapTheme): {
+  resolvedTheme: BasemapTheme;
+  themeKey: string;
+} {
+  const [detected, setDetected] = useState<BasemapTheme>(() => getBrandTheme() ?? getSystemTheme());
+  const [themeAttr, setThemeAttr] = useState(getThemeAttribute);
+
+  useEffect(() => {
+    const update = () => {
+      setThemeAttr(getThemeAttribute());
+      const brand = getBrandTheme();
+      if (brand) setDetected(brand);
+    };
+    const observer = new MutationObserver(update);
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["data-theme", "class"],
+    });
+
+    const mediaQuery =
+      typeof window.matchMedia === "function"
+        ? window.matchMedia("(prefers-color-scheme: dark)")
+        : null;
+    const handleSystemChange = (e: MediaQueryListEvent) => {
+      if (!getBrandTheme()) setDetected(e.matches ? "dark" : "light");
+    };
+    mediaQuery?.addEventListener("change", handleSystemChange);
+
+    return () => {
+      observer.disconnect();
+      mediaQuery?.removeEventListener("change", handleSystemChange);
+    };
+  }, []);
+
+  const resolvedTheme = themeProp ?? detected;
+  return { resolvedTheme, themeKey: `${themeAttr}:${resolvedTheme}` };
+}

package/src/map-cluster-layer/index.ts

@@ -0,0 +1 @@
+export { MapClusterLayer, type MapClusterLayerProps } from "./map-cluster-layer";

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

@@ -0,0 +1,56 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+
+import { MapCanvas } from "../map-canvas";
+import { MapClusterLayer } from "./map-cluster-layer";
+
+// Deterministic pseudo-random points (seeded LCG, stable across renders).
+function makePoints(count: number): GeoJSON.FeatureCollection<GeoJSON.Point, { id: number }> {
+  let seed = 42;
+  const next = () => {
+    seed = (seed * 1664525 + 1013904223) % 4294967296;
+    return seed / 4294967296;
+  };
+  const features: GeoJSON.Feature<GeoJSON.Point, { id: number }>[] = [];
+  for (let i = 0; i < count; i += 1) {
+    // Cluster the points around a handful of European hubs.
+    const hubs: [number, number][] = [
+      [13.4, 52.5],
+      [2.35, 48.85],
+      [-0.13, 51.51],
+      [12.5, 41.9],
+      [-3.7, 40.42],
+    ];
+    const hub = hubs[Math.floor(next() * hubs.length)]!;
+    features.push({
+      type: "Feature",
+      properties: { id: i },
+      geometry: {
+        type: "Point",
+        coordinates: [hub[0] + (next() - 0.5) * 6, hub[1] + (next() - 0.5) * 4],
+      },
+    });
+  }
+  return { type: "FeatureCollection", features };
+}
+
+const points = makePoints(1200);
+
+const meta = {
+  title: "Maps/MapClusterLayer",
+  component: MapClusterLayer,
+  tags: ["autodocs"],
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof MapClusterLayer>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Cluster circles step through the status tokens as point counts grow; click a cluster to zoom in. */
+export const Default: Story = {
+  render: () => (
+    <div className="h-[480px]">
+      <MapCanvas center={[5, 47]} zoom={3.5}>
+        <MapClusterLayer data={points} clusterThresholds={[50, 200]} />
+      </MapCanvas>
+    </div>
+  ),
+};