@elabs-ai/components-maps 4.0.0

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

@@ -0,0 +1,124 @@
+import { useEffect, useState } from "react";
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { resolveTokenColor } from "@elabs-ai/components-tokens";
+
+import { MapCanvas } from "../map-canvas";
+import { MapGeoJSON } from "./map-geojson";
+
+/**
+ * Theme-reactive token resolution for CONSUMER-side paint (outside the map
+ * context). A one-shot `resolveTokenColor` at render time can read the `:root`
+ * fallback: Storybook's theme decorator stamps `data-theme` after the first
+ * render (the sweep caught the blue `:root` primary instead of the active
+ * theme's own).
+ * Re-resolve whenever the theme attribute changes — the same contract the
+ * package's internal `useTokenColor` follows.
+ */
+function useThemedTokenColor(name: string): string {
+  const [color, setColor] = useState("#000000");
+  useEffect(() => {
+    const update = () => setColor(resolveTokenColor(name));
+    update();
+    const observer = new MutationObserver(update);
+    observer.observe(document.documentElement, {
+      attributes: true,
+      attributeFilter: ["data-theme", "class"],
+    });
+    return () => observer.disconnect();
+  }, [name]);
+  return color;
+}
+
+type RegionProps = { name: string; value: number };
+
+// A synthetic "regions" grid (offline-friendly stand-in for country shapes).
+function makeRegions(): GeoJSON.FeatureCollection<GeoJSON.Polygon, RegionProps> {
+  const features: GeoJSON.Feature<GeoJSON.Polygon, RegionProps>[] = [];
+  let i = 0;
+  for (let row = 0; row < 4; row += 1) {
+    for (let col = 0; col < 6; col += 1) {
+      const x = -12 + col * 8;
+      const y = 38 + row * 5;
+      i += 1;
+      features.push({
+        type: "Feature",
+        id: `r${i}`,
+        properties: { name: `Region ${i}`, value: ((i * 37) % 100) / 100 },
+        geometry: {
+          type: "Polygon",
+          coordinates: [
+            [
+              [x, y],
+              [x + 7.4, y],
+              [x + 7.4, y + 4.4],
+              [x, y + 4.4],
+              [x, y],
+            ],
+          ],
+        },
+      });
+    }
+  }
+  return { type: "FeatureCollection", features };
+}
+
+const regions = makeRegions();
+
+const meta = {
+  title: "Maps/MapGeoJSON",
+  component: MapGeoJSON,
+  tags: ["autodocs"],
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof MapGeoJSON>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** Neutral fills + hairline outlines from the theme tokens, on a blank canvas. */
+export const Default: Story = {
+  render: () => (
+    <div className="h-[480px]">
+      <MapCanvas blank center={[10, 48]} zoom={3.2}>
+        <MapGeoJSON data={regions} />
+      </MapCanvas>
+    </div>
+  ),
+};
+
+function ChoroplethDemo() {
+  const [hovered, setHovered] = useState<RegionProps | null>(null);
+  // WebGL paint can't read CSS variables — resolve the token, re-resolving on
+  // theme change (the same mechanism the package uses for its own defaults).
+  const primary = useThemedTokenColor("--primary");
+  return (
+    <div className="relative h-[480px]">
+      <MapCanvas blank center={[10, 48]} zoom={3.2}>
+        <MapGeoJSON<RegionProps>
+          data={regions}
+          promoteId="name"
+          interactive
+          fillPaint={{
+            "fill-color": primary,
+            "fill-opacity": [
+              "interpolate",
+              ["linear"],
+              ["get", "value"],
+              0,
+              0.15,
+              1,
+              0.95,
+            ] as never,
+          }}
+          fillHoverPaint={{ "fill-opacity": 1 }}
+          onHover={(e) => setHovered(e?.feature.properties ?? null)}
+        />
+      </MapCanvas>
+      <div className="absolute top-2 left-2 rounded-md border bg-card px-3 py-2 text-caption text-card-foreground shadow-sm">
+        {hovered ? `${hovered.name}: ${(hovered.value * 100).toFixed(0)}%` : "Hover a region…"}
+      </div>
+    </div>
+  );
+}
+
+export const InteractiveHover: Story = {
+  render: () => <ChoroplethDemo />,
+};

package/src/map-geojson/map-geojson.tsx

@@ -0,0 +1,274 @@
+"use client";
+
+import type MapLibreGL from "maplibre-gl";
+import { useEffect, useId, useMemo, useRef } from "react";
+
+import { useMap } from "../map-canvas/map-context";
+import { mergeHoverPaint } from "../lib/merge-hover-paint";
+import { useTokenColor } from "../lib/use-token-color";
+
+export type MapGeoJSONData<P extends GeoJSON.GeoJsonProperties = GeoJSON.GeoJsonProperties> =
+  | GeoJSON.FeatureCollection<GeoJSON.Geometry, P>
+  | GeoJSON.Feature<GeoJSON.Geometry, P>
+  | GeoJSON.Geometry
+  | string;
+
+export type MapFillPaint = NonNullable<MapLibreGL.FillLayerSpecification["paint"]>;
+export type MapLinePaint = NonNullable<MapLibreGL.LineLayerSpecification["paint"]>;
+
+/** A rendered feature with strongly-typed `properties`. */
+export type MapGeoJSONFeature<P extends GeoJSON.GeoJsonProperties = GeoJSON.GeoJsonProperties> =
+  Omit<MapLibreGL.MapGeoJSONFeature, "properties"> & { properties: P };
+
+/** Event payload passed to MapGeoJSON interaction callbacks. */
+export type MapGeoJSONEvent<P extends GeoJSON.GeoJsonProperties = GeoJSON.GeoJsonProperties> = {
+  /** The feature under the cursor, with its typed GeoJSON properties. */
+  feature: MapGeoJSONFeature<P>;
+  /** 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.MapLayerMouseEvent;
+};
+
+export type MapGeoJSONProps<P extends GeoJSON.GeoJsonProperties = GeoJSON.GeoJsonProperties> = {
+  /** GeoJSON data (FeatureCollection, Feature, Geometry) or a URL to fetch it from. */
+  data: MapGeoJSONData<P>;
+  /** Optional unique identifier prefix for the source/layers. Auto-generated if not provided. */
+  id?: string;
+  /**
+   * Feature property to promote to the feature `id`. Required for hover
+   * feature-state (`fillHoverPaint`) and stable `onHover`/`onClick` payloads.
+   */
+  promoteId?: string;
+  /**
+   * Paint for the polygon fill layer. Merged on top of a theme-aware neutral
+   * default (the `--border` token — a mid neutral that reads on the page
+   * surface in every theme). Pass `false` to omit the fill layer entirely
+   * (e.g. outlines only).
+   */
+  fillPaint?: MapFillPaint | false;
+  /**
+   * Paint for the outline layer. Merged on top of a hairline default
+   * (`line-color` = the `--background` token, `line-width` = 0.5) for thin
+   * separators. Override `line-color` if your container differs, or pass
+   * `false` to omit the layer.
+   */
+  linePaint?: MapLinePaint | false;
+  /**
+   * Paint merged onto the fill layer for the feature under the cursor, applied
+   * as a `case` expression keyed on hover feature-state. Requires `promoteId`.
+   */
+  fillHoverPaint?: MapFillPaint;
+  /** Callback when a feature is clicked. */
+  onClick?: (e: MapGeoJSONEvent<P>) => void;
+  /** Callback fired when the hovered feature changes; `null` when the cursor leaves. */
+  onHover?: (e: MapGeoJSONEvent<P> | null) => void;
+  /** Whether features respond to mouse events (default: false). */
+  interactive?: boolean;
+  /** Optional MapLibre layer id to insert the layers before (z-order control). */
+  beforeId?: string;
+};
+
+/**
+ * Renders arbitrary GeoJSON as fill + outline layers on the map. Composes like
+ * `MapRoute` / `MapArc` — drop it inside `<MapCanvas>` (typically with `blank`)
+ * for choropleths and region/data maps. For full control over expressions and
+ * multiple layers, manage layers directly via `useMap()` instead.
+ */
+export function MapGeoJSON<P extends GeoJSON.GeoJsonProperties = GeoJSON.GeoJsonProperties>({
+  data,
+  id: propId,
+  promoteId,
+  fillPaint,
+  linePaint,
+  fillHoverPaint,
+  onClick,
+  onHover,
+  interactive = false,
+  beforeId,
+}: MapGeoJSONProps<P>) {
+  const { map, isLoaded } = useMap();
+  const autoId = useId();
+  const id = propId ?? autoId;
+  const sourceId = `geojson-source-${id}`;
+  const fillLayerId = `geojson-fill-${id}`;
+  const lineLayerId = `geojson-line-${id}`;
+
+  // Theme-driven neutral defaults: landmass = the mid-neutral `--border` rung,
+  // separators = the page surface. Both re-resolve on theme change.
+  const defaultFill = useTokenColor("--border");
+  const defaultLine = useTokenColor("--background");
+
+  const showFill = fillPaint !== false;
+  const showLine = linePaint !== false;
+
+  const mergedFillPaint = useMemo(
+    () => mergeHoverPaint({ "fill-color": defaultFill, ...(fillPaint || {}) }, fillHoverPaint),
+    [defaultFill, fillPaint, fillHoverPaint],
+  );
+  const mergedLinePaint = useMemo(
+    () => ({
+      "line-color": defaultLine,
+      "line-width": 0.5,
+      ...(linePaint || {}),
+    }),
+    [defaultLine, linePaint],
+  );
+  const latestRef = useRef({ onClick, onHover });
+  latestRef.current = { onClick, onHover };
+
+  // Add source on mount.
+  useEffect(() => {
+    if (!isLoaded || !map) return;
+
+    map.addSource(sourceId, {
+      type: "geojson",
+      data,
+      ...(promoteId ? { promoteId } : {}),
+    });
+
+    return () => {
+      try {
+        if (map.getLayer(lineLayerId)) map.removeLayer(lineLayerId);
+        if (map.getLayer(fillLayerId)) map.removeLayer(fillLayerId);
+        if (map.getSource(sourceId)) map.removeSource(sourceId);
+      } catch {
+        // style may be mid-reload
+      }
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps -- source created once per map; data/layers are synced by the effects below
+  }, [isLoaded, map]);
+
+  // Sync data when it changes.
+  useEffect(() => {
+    if (!isLoaded || !map) return;
+    const source = map.getSource(sourceId) as MapLibreGL.GeoJSONSource | undefined;
+    source?.setData(data as never);
+  }, [isLoaded, map, data, sourceId]);
+
+  // Sync layers and paint when visibility or styling changes.
+  useEffect(() => {
+    if (!isLoaded || !map) return;
+
+    const source = map.getSource(sourceId);
+    if (!source) return;
+
+    if (showFill && !map.getLayer(fillLayerId)) {
+      map.addLayer(
+        {
+          id: fillLayerId,
+          type: "fill",
+          source: sourceId,
+          paint: mergedFillPaint,
+        },
+        beforeId,
+      );
+    } else if (!showFill && map.getLayer(fillLayerId)) {
+      map.removeLayer(fillLayerId);
+    }
+
+    if (showLine && !map.getLayer(lineLayerId)) {
+      map.addLayer(
+        {
+          id: lineLayerId,
+          type: "line",
+          source: sourceId,
+          paint: mergedLinePaint,
+        },
+        beforeId,
+      );
+    } else if (!showLine && map.getLayer(lineLayerId)) {
+      map.removeLayer(lineLayerId);
+    }
+
+    if (showFill && map.getLayer(fillLayerId)) {
+      for (const [key, value] of Object.entries(mergedFillPaint)) {
+        map.setPaintProperty(fillLayerId, key as keyof MapFillPaint, value as never);
+      }
+    }
+    if (showLine && map.getLayer(lineLayerId)) {
+      for (const [key, value] of Object.entries(mergedLinePaint)) {
+        map.setPaintProperty(lineLayerId, key as keyof MapLinePaint, value as never);
+      }
+    }
+  }, [
+    isLoaded,
+    map,
+    sourceId,
+    fillLayerId,
+    lineLayerId,
+    showFill,
+    showLine,
+    mergedFillPaint,
+    mergedLinePaint,
+    beforeId,
+  ]);
+
+  // Interaction handlers (bound to the fill layer).
+  useEffect(() => {
+    if (!isLoaded || !map || !interactive || !showFill) 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 handleMouseMove = (e: MapLibreGL.MapLayerMouseEvent) => {
+      const feature = e.features?.[0];
+      if (!feature) return;
+      map.getCanvas().style.cursor = "pointer";
+
+      const featureId = feature.id;
+      if (featureId === hoveredId) return;
+      setHover(featureId ?? null);
+      latestRef.current.onHover?.({
+        feature: feature as unknown as MapGeoJSONFeature<P>,
+        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 feature = e.features?.[0];
+      if (!feature) return;
+      latestRef.current.onClick?.({
+        feature: feature as unknown as MapGeoJSONFeature<P>,
+        longitude: e.lngLat.lng,
+        latitude: e.lngLat.lat,
+        originalEvent: e,
+      });
+    };
+
+    map.on("mousemove", fillLayerId, handleMouseMove);
+    map.on("mouseleave", fillLayerId, handleMouseLeave);
+    map.on("click", fillLayerId, handleClick);
+
+    return () => {
+      map.off("mousemove", fillLayerId, handleMouseMove);
+      map.off("mouseleave", fillLayerId, handleMouseLeave);
+      map.off("click", fillLayerId, handleClick);
+      setHover(null);
+      map.getCanvas().style.cursor = "";
+    };
+  }, [isLoaded, map, fillLayerId, sourceId, interactive, showFill]);
+
+  return null;
+}

package/src/map-marker/index.ts

@@ -0,0 +1,12 @@
+export {
+  MapMarker,
+  MapMarkerContent,
+  MapMarkerPopup,
+  MapMarkerTooltip,
+  MapMarkerLabel,
+  type MapMarkerProps,
+  type MapMarkerContentProps,
+  type MapMarkerPopupProps,
+  type MapMarkerTooltipProps,
+  type MapMarkerLabelProps,
+} from "./map-marker";

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

@@ -0,0 +1,71 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { MapPin } from "lucide-react";
+
+import { MapCanvas } from "../map-canvas";
+import {
+  MapMarker,
+  MapMarkerContent,
+  MapMarkerLabel,
+  MapMarkerPopup,
+  MapMarkerTooltip,
+} from "./map-marker";
+
+const meta = {
+  title: "Maps/MapMarker",
+  component: MapMarker,
+  tags: ["autodocs"],
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof MapMarker>;
+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}>
+        <MapMarker longitude={13.405} latitude={52.52}>
+          <MapMarkerContent />
+          <MapMarkerLabel>Berlin</MapMarkerLabel>
+        </MapMarker>
+      </MapCanvas>
+    </div>
+  ),
+};
+
+export const WithPopupAndTooltip: Story = {
+  render: () => (
+    <div className="h-[480px]">
+      <MapCanvas center={[13.41, 52.52]} zoom={12}>
+        <MapMarker longitude={13.405} latitude={52.52}>
+          <MapMarkerContent />
+          <MapMarkerTooltip>Click for details</MapMarkerTooltip>
+          <MapMarkerPopup closeButton>
+            <p className="text-body font-medium">Alexanderplatz</p>
+            <p className="text-caption text-muted-foreground">
+              Public square in the Mitte district.
+            </p>
+          </MapMarkerPopup>
+        </MapMarker>
+        <MapMarker longitude={13.377} latitude={52.516}>
+          <MapMarkerContent>
+            <MapPin className="size-6 text-primary" aria-hidden="true" />
+          </MapMarkerContent>
+          <MapMarkerLabel position="bottom">Brandenburg Gate</MapMarkerLabel>
+        </MapMarker>
+      </MapCanvas>
+    </div>
+  ),
+};
+
+export const Draggable: Story = {
+  render: () => (
+    <div className="h-[480px]">
+      <MapCanvas center={[13.405, 52.52]} zoom={11}>
+        <MapMarker longitude={13.405} latitude={52.52} draggable>
+          <MapMarkerContent />
+          <MapMarkerLabel>Drag me</MapMarkerLabel>
+        </MapMarker>
+      </MapCanvas>
+    </div>
+  ),
+};

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

@@ -0,0 +1,81 @@
+import { cleanup, render, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+vi.mock("maplibre-gl", async () => {
+  const { createMaplibreMock } = await import("../test-utils/maplibre-mock");
+  return createMaplibreMock();
+});
+
+import { MockMarker, resetMaplibreMock } from "../test-utils/maplibre-mock";
+import { MapCanvas } from "../map-canvas";
+import { MapMarker, MapMarkerContent, MapMarkerLabel } from "./map-marker";
+
+afterEach(() => {
+  cleanup();
+  resetMaplibreMock();
+});
+
+describe("MapMarker", () => {
+  it("adds the marker to the map at the given position", async () => {
+    render(
+      <MapCanvas>
+        <MapMarker longitude={13.4} latitude={52.52}>
+          <MapMarkerContent />
+        </MapMarker>
+      </MapCanvas>,
+    );
+    await waitFor(() => {
+      expect(MockMarker.instances).toHaveLength(1);
+      expect(MockMarker.instances[0]!.addedTo).not.toBeNull();
+    });
+    expect(MockMarker.instances[0]!.lngLat).toEqual({ lng: 13.4, lat: 52.52 });
+  });
+
+  it("portals content into the marker element (default icon)", async () => {
+    render(
+      <MapCanvas>
+        <MapMarker longitude={0} latitude={0}>
+          <MapMarkerContent />
+        </MapMarker>
+      </MapCanvas>,
+    );
+    await waitFor(() => {
+      expect(MockMarker.instances[0]!.element.querySelector(".bg-primary")).not.toBeNull();
+    });
+  });
+
+  it("renders custom content and labels", async () => {
+    render(
+      <MapCanvas>
+        <MapMarker longitude={0} latitude={0}>
+          <MapMarkerContent>
+            <span data-testid="pin">pin</span>
+          </MapMarkerContent>
+          <MapMarkerLabel>Berlin</MapMarkerLabel>
+        </MapMarker>
+      </MapCanvas>,
+    );
+    await waitFor(() => {
+      const el = MockMarker.instances[0]!.element;
+      expect(el.querySelector("[data-testid='pin']")).not.toBeNull();
+      // The label anchors to the marker element even when composed as a
+      // SIBLING of MapMarkerContent (it portals itself).
+      expect(el.textContent).toContain("Berlin");
+    });
+  });
+
+  it("removes the marker on unmount", async () => {
+    const { unmount } = render(
+      <MapCanvas>
+        <MapMarker longitude={0} latitude={0}>
+          <MapMarkerContent />
+        </MapMarker>
+      </MapCanvas>,
+    );
+    await waitFor(() => {
+      expect(MockMarker.instances[0]!.addedTo).not.toBeNull();
+    });
+    unmount();
+    expect(MockMarker.instances[0]!.addedTo).toBeNull();
+  });
+});