@elabs-ai/components-maps 4.2.0 → 5.0.0

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

@@ -0,0 +1,216 @@
+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 { MockMap, resetMaplibreMock } from "../test-utils/maplibre-mock";
+import { MapCanvas } from "../map-canvas";
+import { createPlanCrs } from "../lib/plan-crs";
+import { MapRoute } from "./map-route";
+
+afterEach(() => {
+  cleanup();
+  resetMaplibreMock();
+  vi.restoreAllMocks();
+});
+
+const PLAN = { width: 1000, height: 500 };
+
+function lastMap() {
+  return MockMap.instances.at(-1)!;
+}
+
+function sourceData(map: MockMap) {
+  const source = [...map.sources.values()][0]!;
+  return source.setDataCalls.at(-1) as GeoJSON.Feature<GeoJSON.LineString> | undefined;
+}
+
+/** A 2D context stub, so the generated chevron exists in jsdom too. */
+function stubCanvasContext() {
+  vi.spyOn(HTMLCanvasElement.prototype, "getContext").mockImplementation(function (kind: string) {
+    if (kind !== "2d") return null;
+    return {
+      strokeStyle: "",
+      lineWidth: 0,
+      lineCap: "butt",
+      lineJoin: "miter",
+      clearRect: () => {},
+      beginPath: () => {},
+      moveTo: () => {},
+      lineTo: () => {},
+      stroke: () => {},
+      getImageData: (_x: number, _y: number, width: number, height: number) => ({
+        data: new Uint8ClampedArray(width * height * 4),
+      }),
+    } as unknown as CanvasRenderingContext2D;
+  });
+}
+
+describe("MapRoute", () => {
+  it("passes geographic coordinates through as they were given", async () => {
+    const coordinates: [number, number][] = [
+      [13.4, 52.5],
+      [2.35, 48.86],
+    ];
+    render(
+      <MapCanvas>
+        <MapRoute coordinates={coordinates} />
+      </MapCanvas>,
+    );
+
+    await waitFor(() => {
+      expect(sourceData(lastMap())).toBeDefined();
+    });
+    expect(sourceData(lastMap())!.geometry.coordinates).toBe(coordinates);
+  });
+
+  it("converts plan coordinates into the plan's own lng/lat", async () => {
+    const coordinates: [number, number][] = [
+      [0, 0],
+      [1000, 500],
+    ];
+    render(
+      <MapCanvas plan={PLAN}>
+        <MapRoute coordinates={coordinates} />
+      </MapCanvas>,
+    );
+
+    await waitFor(() => {
+      expect(sourceData(lastMap())).toBeDefined();
+    });
+
+    const crs = createPlanCrs(PLAN);
+    expect(sourceData(lastMap())!.geometry.coordinates).toEqual([
+      crs.toLngLat({ x: 0, y: 0 }),
+      crs.toLngLat({ x: 1000, y: 500 }),
+    ]);
+    // The caller's array is never mutated.
+    expect(coordinates[1]).toEqual([1000, 500]);
+  });
+
+  it("draws no arrows by default", async () => {
+    render(
+      <MapCanvas>
+        <MapRoute
+          coordinates={[
+            [0, 0],
+            [10, 10],
+          ]}
+        />
+      </MapCanvas>,
+    );
+
+    await waitFor(() => {
+      expect(lastMap().layers.size).toBeGreaterThan(0);
+    });
+    expect([...lastMap().layers.keys()].some((id) => id.startsWith("route-arrows-"))).toBe(false);
+    expect(lastMap().addImageCalls).toHaveLength(0);
+  });
+
+  it("registers the chevron and places it along the line when asked", async () => {
+    stubCanvasContext();
+    render(
+      <MapCanvas>
+        <MapRoute
+          id="aisle"
+          coordinates={[
+            [0, 0],
+            [10, 10],
+          ]}
+          direction="forward"
+        />
+      </MapCanvas>,
+    );
+
+    await waitFor(() => {
+      expect(lastMap().getLayer("route-arrows-aisle")).toBeDefined();
+    });
+
+    const [id, , options] = lastMap().addImageCalls.at(-1)!;
+    expect(id).toBe("route-arrow-aisle");
+    expect(options).toEqual({ pixelRatio: 2 });
+
+    const layer = lastMap().getLayer("route-arrows-aisle");
+    expect(layer.type).toBe("symbol");
+    expect(layer.layout).toMatchObject({
+      "symbol-placement": "line",
+      "icon-image": "route-arrow-aisle",
+      "icon-rotate": 0,
+      "icon-rotation-alignment": "map",
+    });
+    // An icon, never a `text-field`: a blank style has no glyph endpoint, so
+    // text on a symbol layer would silently render nothing.
+    expect(layer.layout["text-field"]).toBeUndefined();
+  });
+
+  it("turns the chevron around for a backward route", async () => {
+    stubCanvasContext();
+    render(
+      <MapCanvas>
+        <MapRoute
+          id="belt"
+          coordinates={[
+            [0, 0],
+            [10, 10],
+          ]}
+          direction="backward"
+        />
+      </MapCanvas>,
+    );
+
+    await waitFor(() => {
+      expect(lastMap().getLayer("route-arrows-belt")).toBeDefined();
+    });
+    expect(lastMap().getLayer("route-arrows-belt").layout["icon-rotate"]).toBe(180);
+  });
+
+  it("leaves the arrow layer out when there is no canvas to draw it on", async () => {
+    // Unstubbed jsdom: no 2D context, so no image — and a layer pointing at a
+    // missing image would warn on every frame.
+    render(
+      <MapCanvas>
+        <MapRoute
+          id="aisle"
+          coordinates={[
+            [0, 0],
+            [10, 10],
+          ]}
+          direction="forward"
+        />
+      </MapCanvas>,
+    );
+
+    await waitFor(() => {
+      expect(lastMap().layers.size).toBeGreaterThan(0);
+    });
+    expect(lastMap().getLayer("route-arrows-aisle")).toBeUndefined();
+  });
+
+  it("takes its arrow layer and image away again on unmount", async () => {
+    stubCanvasContext();
+    const { unmount } = render(
+      <MapCanvas>
+        <MapRoute
+          id="aisle"
+          coordinates={[
+            [0, 0],
+            [10, 10],
+          ]}
+          direction="forward"
+        />
+      </MapCanvas>,
+    );
+
+    await waitFor(() => {
+      expect(lastMap().getLayer("route-arrows-aisle")).toBeDefined();
+    });
+    const map = lastMap();
+    unmount();
+
+    expect(map.getLayer("route-arrows-aisle")).toBeUndefined();
+    expect(map.hasImage("route-arrow-aisle")).toBe(false);
+  });
+});

package/src/map-route/map-route.tsx

@@ -1,15 +1,22 @@
 "use client";
 
 import type MapLibreGL from "maplibre-gl";
-import { useEffect, useId } from "react";
+import { useEffect, useId, useMemo } from "react";
 
 import { useMap } from "../map-canvas/map-context";
 import { useTokenColor } from "../lib/use-token-color";
+import { createRouteArrowImage, routeArrowImageId } from "../lib/route-arrow";
+
+/** Which way the route runs, drawn as chevrons along the line. */
+export type MapRouteDirection = "none" | "forward" | "backward";
 
 export interface MapRouteProps {
   /** Optional unique identifier for the route layer. */
   id?: string;
-  /** Array of [longitude, latitude] coordinate pairs defining the route. */
+  /**
+   * Array of [longitude, latitude] coordinate pairs defining the route — or, in
+   * a `<MapCanvas plan>`, [x, y] pairs in plan units.
+   */
   coordinates: [number, number][];
   /** Line color as a CSS color value. Defaults to the theme's `--primary` token. */
   color?: string;
@@ -19,6 +26,14 @@ export interface MapRouteProps {
   opacity?: number;
   /** Dash pattern [dash length, gap length] for dashed lines. */
   dashArray?: [number, number];
+  /**
+   * Draw chevrons along the line to show which way it runs (default: "none").
+   * A conveyor, a one-way aisle and a walking route all need this, and an arrow
+   * is a second channel that greyscale keeps.
+   */
+  direction?: MapRouteDirection;
+  /** Distance between chevrons in px (default: 80). */
+  directionSpacing?: number;
   /** Callback when the route line is clicked. */
   onClick?: () => void;
   /** Callback when the mouse enters the route line. */
@@ -37,20 +52,31 @@ export function MapRoute({
   width = 3,
   opacity = 0.8,
   dashArray,
+  direction = "none",
+  directionSpacing = 80,
   onClick,
   onMouseEnter,
   onMouseLeave,
   interactive = true,
 }: MapRouteProps) {
-  const { map, isLoaded } = useMap();
+  const { map, isLoaded, plan } = useMap();
   const autoId = useId();
   const id = propId ?? autoId;
   const sourceId = `route-source-${id}`;
   const layerId = `route-layer-${id}`;
+  const arrowLayerId = `route-arrows-${id}`;
+  const arrowImageId = routeArrowImageId(id);
 
   const primary = useTokenColor("--primary");
   const lineColor = color ?? primary;
 
+  // On a plan map the pairs are plan units; on a geographic one they are handed
+  // through untouched, identity included.
+  const resolvedCoordinates = useMemo(
+    () => (plan ? coordinates.map((point) => plan.toLngLat(point)) : coordinates),
+    [plan, coordinates],
+  );
+
   // Add source and layer on mount.
   useEffect(() => {
     if (!isLoaded || !map) return;
@@ -90,17 +116,90 @@ export function MapRoute({
 
   // When coordinates change, update the source data.
   useEffect(() => {
-    if (!isLoaded || !map || coordinates.length < 2) return;
+    if (!isLoaded || !map || resolvedCoordinates.length < 2) return;
 
     const source = map.getSource(sourceId) as MapLibreGL.GeoJSONSource;
     if (source) {
       source.setData({
         type: "Feature",
         properties: {},
-        geometry: { type: "LineString", coordinates },
+        geometry: { type: "LineString", coordinates: resolvedCoordinates },
       });
     }
-  }, [isLoaded, map, coordinates, sourceId]);
+  }, [isLoaded, map, resolvedCoordinates, sourceId]);
+
+  // Direction chevrons: a generated icon, re-registered whenever the ink
+  // changes, with the layer added only once the image really exists.
+  useEffect(() => {
+    if (!isLoaded || !map || direction === "none") return;
+
+    const image = createRouteArrowImage(lineColor);
+    if (!image) return;
+
+    let cancelled = false;
+
+    const register = () => {
+      try {
+        if (map.hasImage(arrowImageId)) {
+          map.updateImage(arrowImageId, image as unknown as ImageData);
+        } else {
+          map.addImage(arrowImageId, image as unknown as ImageData, { pixelRatio: 2 });
+        }
+        if (!map.getLayer(arrowLayerId)) {
+          map.addLayer({
+            id: arrowLayerId,
+            type: "symbol",
+            source: sourceId,
+            layout: {
+              "symbol-placement": "line",
+              "symbol-spacing": directionSpacing,
+              "icon-image": arrowImageId,
+              "icon-rotate": direction === "backward" ? 180 : 0,
+              "icon-rotation-alignment": "map",
+              "icon-allow-overlap": true,
+              "icon-ignore-placement": true,
+            },
+            paint: { "icon-opacity": opacity },
+          });
+        } else {
+          map.setLayoutProperty(arrowLayerId, "symbol-spacing", directionSpacing);
+          map.setLayoutProperty(arrowLayerId, "icon-rotate", direction === "backward" ? 180 : 0);
+          map.setPaintProperty(arrowLayerId, "icon-opacity", opacity);
+        }
+      } catch {
+        // style mid-reload; `styledata` re-runs this
+      }
+    };
+
+    register();
+    // A theme swap calls setStyle, which drops every style image AND every layer
+    // this component added.
+    const onStyleData = () => {
+      if (!cancelled) register();
+    };
+    map.on("styledata", onStyleData);
+
+    return () => {
+      cancelled = true;
+      map.off("styledata", onStyleData);
+      try {
+        if (map.getLayer(arrowLayerId)) map.removeLayer(arrowLayerId);
+        if (map.hasImage(arrowImageId)) map.removeImage(arrowImageId);
+      } catch {
+        // style may be mid-reload
+      }
+    };
+  }, [
+    isLoaded,
+    map,
+    direction,
+    directionSpacing,
+    lineColor,
+    opacity,
+    sourceId,
+    arrowLayerId,
+    arrowImageId,
+  ]);
 
   // Sync paint when styling (or the resolved theme color) changes.
   useEffect(() => {

package/src/map-scale-bar/index.ts

@@ -0,0 +1,9 @@
+export {
+  MapScaleBar,
+  computeMapScale,
+  metresPerPixel,
+  niceDistance,
+  type MapScaleBarProps,
+  type MapScaleUnit,
+  type MapScale,
+} from "./map-scale-bar";

package/src/map-scale-bar/map-scale-bar.stories.tsx

@@ -0,0 +1,63 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, waitFor } from "storybook/test";
+
+import { MapCanvas } from "../map-canvas";
+import { MapScaleBar } from "./map-scale-bar";
+
+const meta = {
+  title: "Maps/MapScaleBar",
+  component: MapScaleBar,
+  tags: ["autodocs"],
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof MapScaleBar>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * A kilometre bar at the bottom-left. Its length snaps to a round distance
+ * (1, 2, 5 × 10ⁿ) and is recomputed whenever the view or the map width
+ * changes — a narrow map gets a shorter bar.
+ */
+export const Default: Story = {
+  render: (args) => (
+    <div className="w-full p-4">
+      <MapCanvas interactive={false} center={[-78.2, 43.7]} zoom={6.5}>
+        <MapScaleBar {...args} />
+      </MapCanvas>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    if (!canvasElement.querySelector(".maplibregl-canvas")) return;
+    const bar = await waitFor(() => {
+      const el = canvasElement.querySelector<HTMLElement>('[data-slot="map-scale-bar"]');
+      expect(el).not.toBeNull();
+      expect(Number(el!.dataset.distance)).toBeGreaterThan(0);
+      return el!;
+    });
+    await expect(bar).toHaveAttribute("data-unit", "kilometer");
+  },
+};
+
+/** Miles, in the bottom-right corner. */
+export const Miles: Story = {
+  args: { unit: "mi", position: "bottom-right" },
+  render: Default.render,
+};
+
+/** Zoomed in far enough that the bar switches to metres. */
+export const Metres: Story = {
+  args: { position: "top-left" },
+  render: (args) => (
+    <div className="w-full p-4">
+      <MapCanvas interactive={false} center={[-79.38, 43.65]} zoom={15}>
+        <MapScaleBar {...args} />
+      </MapCanvas>
+    </div>
+  ),
+};
+
+/** The last corner. */
+export const TopRight: Story = {
+  args: { position: "top-right" },
+  render: Default.render,
+};

package/src/map-scale-bar/map-scale-bar.test.tsx

@@ -0,0 +1,65 @@
+import { act, cleanup, render, screen } 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 { MockMap, resetMaplibreMock } from "../test-utils/maplibre-mock";
+import { MapCanvas } from "../map-canvas";
+import { MapScaleBar, computeMapScale, metresPerPixel, niceDistance } from "./map-scale-bar";
+
+afterEach(() => {
+  cleanup();
+  resetMaplibreMock();
+});
+
+describe("computeMapScale", () => {
+  it("measures Web Mercator metres per pixel", () => {
+    // 512 px world at zoom 0 on the equator.
+    expect(metresPerPixel(0, 0)).toBeCloseTo(40_075_016.686 / 512, 3);
+    expect(metresPerPixel(60, 1)).toBeCloseTo(40_075_016.686 / 512 / 4, 3);
+  });
+
+  it("rounds to 1 / 2 / 5 × 10ⁿ", () => {
+    expect(niceDistance(87)).toBe(50);
+    expect(niceDistance(230)).toBe(200);
+    expect(niceDistance(1.4)).toBe(1);
+    expect(niceDistance(0)).toBe(0);
+  });
+
+  it("recomputes the distance for a narrower bar and switches units", () => {
+    const wide = computeMapScale(43.6, 7, "km", 112);
+    const narrow = computeMapScale(43.6, 6.3, "km", 80);
+    expect(wide.unit).toBe("kilometer");
+    expect(narrow.value).not.toBe(wide.value);
+    expect(wide.px).toBeLessThanOrEqual(112);
+    expect(narrow.px).toBeLessThanOrEqual(80);
+    expect(computeMapScale(43.6, 16, "km", 100).unit).toBe("meter");
+    expect(computeMapScale(43.6, 7, "mi", 100).unit).toBe("mile");
+    expect(computeMapScale(43.6, 16, "mi", 100).unit).toBe("foot");
+  });
+});
+
+describe("MapScaleBar", () => {
+  it("renders a locale-formatted distance and updates as the map moves", async () => {
+    render(
+      <MapCanvas>
+        <MapScaleBar />
+      </MapCanvas>,
+    );
+    const bar = await screen.findByText(/km/);
+    const first = bar.textContent;
+    const map = MockMap.instances[0]!;
+    act(() => {
+      map.zoom = 4;
+      map.emit("move");
+    });
+    expect(screen.getByText(/km/).textContent).not.toBe(first);
+    expect(document.querySelector('[data-slot="map-scale-bar"]')).toHaveAttribute(
+      "data-unit",
+      "kilometer",
+    );
+  });
+});

package/src/map-scale-bar/map-scale-bar.tsx

@@ -0,0 +1,145 @@
+"use client";
+
+import { forwardRef, useEffect, useState, type HTMLAttributes } from "react";
+import { useLocale } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+
+import { useMap } from "../map-canvas/map-context";
+import { useMapBreakpoint } from "../lib/use-map-breakpoint";
+import { MAP_CORNER_CLASSES, type MapCorner } from "../map-legend/map-corner";
+
+/** Metric (`km`, falling back to metres) or imperial (`mi`, falling back to feet). */
+export type MapScaleUnit = "km" | "mi";
+
+/** The Earth's equatorial circumference in metres (WGS 84), as MapLibre uses it. */
+const EARTH_CIRCUMFERENCE_M = 40_075_016.686;
+/** MapLibre's world size at zoom 0, in CSS px. */
+const TILE_SIZE = 512;
+const METRES_PER_MILE = 1609.344;
+const METRES_PER_FOOT = 0.3048;
+
+/** The longest the bar may draw, per tier (CSS px). */
+const MAX_BAR_PX = { wide: 112, medium: 96, narrow: 80 } as const;
+
+/** Metres one CSS px covers at `latitude` and `zoom` (Web Mercator). */
+export function metresPerPixel(latitude: number, zoom: number): number {
+  return (EARTH_CIRCUMFERENCE_M * Math.cos((latitude * Math.PI) / 180)) / (TILE_SIZE * 2 ** zoom);
+}
+
+/** The largest 1 / 2 / 5 × 10ⁿ that is ≤ `max`. */
+export function niceDistance(max: number): number {
+  if (!(max > 0) || !Number.isFinite(max)) return 0;
+  const magnitude = 10 ** Math.floor(Math.log10(max));
+  for (const step of [5, 2, 1]) {
+    if (step * magnitude <= max) return step * magnitude;
+  }
+  return magnitude;
+}
+
+export interface MapScale {
+  /** The bar's length in CSS px. */
+  px: number;
+  /** The distance the bar stands for, in `unit`. */
+  value: number;
+  /** An `Intl.NumberFormat` unit identifier. */
+  unit: "kilometer" | "meter" | "mile" | "foot";
+}
+
+/**
+ * A round distance that fits in `maxPx` at this latitude and zoom, in `unit`
+ * — kilometres (metres below 1 km) or miles (feet below 1 mi).
+ */
+export function computeMapScale(
+  latitude: number,
+  zoom: number,
+  unit: MapScaleUnit,
+  maxPx: number,
+): MapScale {
+  const perPx = metresPerPixel(latitude, zoom);
+  const maxMetres = perPx * maxPx;
+  const [big, small, bigM, smallM] =
+    unit === "mi"
+      ? (["mile", "foot", METRES_PER_MILE, METRES_PER_FOOT] as const)
+      : (["kilometer", "meter", 1000, 1] as const);
+  const useBig = maxMetres >= bigM;
+  const perUnit = useBig ? bigM : smallM;
+  const value = niceDistance(maxMetres / perUnit);
+  const px = perPx > 0 ? (value * perUnit) / perPx : 0;
+  return { px: Math.max(0, px), value, unit: useBig ? big : small };
+}
+
+export interface MapScaleBarProps extends HTMLAttributes<HTMLDivElement> {
+  /** `km` (default) or `mi`. */
+  unit?: MapScaleUnit;
+  /** Corner of the map (default `"bottom-left"`). */
+  position?: MapCorner;
+}
+
+/**
+ * A scale bar for the map's centre latitude — a round distance ("50 km") and
+ * a bar of that length, re-measured as the map moves or resizes. The bar gets
+ * shorter at `narrow`. Render inside `<MapCanvas>`.
+ */
+export const MapScaleBar = forwardRef<HTMLDivElement, MapScaleBarProps>(function MapScaleBar(
+  { unit = "km", position = "bottom-left", className, ...props },
+  ref,
+) {
+  const { map } = useMap();
+  const { formatNumber } = useLocale();
+  const maxPx = MAX_BAR_PX[useMapBreakpoint()];
+  const [scale, setScale] = useState<MapScale | null>(null);
+
+  useEffect(() => {
+    if (!map) return undefined;
+    const update = () => {
+      const next = computeMapScale(map.getCenter().lat, map.getZoom(), unit, maxPx);
+      setScale((prev) =>
+        prev &&
+        prev.value === next.value &&
+        prev.unit === next.unit &&
+        Math.abs(prev.px - next.px) < 0.5
+          ? prev
+          : next,
+      );
+    };
+    update();
+    map.on("move", update);
+    map.on("resize", update);
+    return () => {
+      map.off("move", update);
+      map.off("resize", update);
+    };
+  }, [map, unit, maxPx]);
+
+  if (!scale || scale.value <= 0) return null;
+  const label = formatNumber(scale.value, {
+    style: "unit",
+    unit: scale.unit,
+    unitDisplay: "short",
+  });
+
+  return (
+    <div
+      ref={ref}
+      data-slot="map-scale-bar"
+      data-unit={scale.unit}
+      data-distance={scale.value}
+      className={cn(
+        "pointer-events-none absolute z-10 flex flex-col items-start gap-0.5 rounded-sm bg-background/80 px-1.5 py-1",
+        MAP_CORNER_CLASSES[position],
+        className,
+      )}
+      {...props}
+    >
+      <span data-slot="map-scale-bar-label" className="text-meta text-foreground tabular-nums">
+        {label}
+      </span>
+      <span
+        aria-hidden="true"
+        data-slot="map-scale-bar-bar"
+        className="block h-1.5 border-x-2 border-b-2 border-foreground"
+        style={{ width: Math.round(scale.px) }}
+      />
+    </div>
+  );
+});