@elabs-ai/components-maps 4.2.0 → 5.1.0

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

@@ -41,3 +41,19 @@ export const TopLeft: Story = {
     </div>
   ),
 };
+
+/**
+ * A static editorial map (`interactive={false}`) shows no zoom chrome: the
+ * gestures those buttons invite are switched off, so the affordance would lie.
+ * The host can still ask for a group explicitly — the fullscreen toggle here
+ * works either way.
+ */
+export const StaticMap: Story = {
+  render: () => (
+    <div className="h-[480px]">
+      <MapCanvas center={[2.3522, 48.8566]} interactive={false} zoom={11}>
+        <MapControls showFullscreen />
+      </MapCanvas>
+    </div>
+  ),
+};

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

@@ -1,6 +1,7 @@
-import { cleanup, render, screen } from "@testing-library/react";
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 import { afterEach, describe, expect, it, vi } from "vitest";
+import { LocaleProvider } from "@elabs-ai/components-ui";
 
 vi.mock("maplibre-gl", async () => {
   const { createMaplibreMock } = await import("../test-utils/maplibre-mock");
@@ -30,6 +31,40 @@ describe("MapControls", () => {
     ).not.toBeInTheDocument();
   });
 
+  it("hides zoom chrome on a static map, and renders no control box at all", async () => {
+    const { container } = render(
+      <MapCanvas interactive={false}>
+        <MapControls />
+      </MapCanvas>,
+    );
+    await waitFor(() => {
+      expect(container.querySelector("[data-slot='map-canvas']")).not.toBeNull();
+    });
+    expect(screen.queryByRole("button", { name: "Zoom in" })).not.toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "Zoom out" })).not.toBeInTheDocument();
+    // No empty, absolutely-positioned control box left behind either.
+    expect(container.querySelector(".absolute.z-10")).toBeNull();
+  });
+
+  it("keeps zoom chrome on a static map when the host asks for it", async () => {
+    render(
+      <MapCanvas interactive={false}>
+        <MapControls showZoom />
+      </MapCanvas>,
+    );
+    expect(await screen.findByRole("button", { name: "Zoom in" })).toBeInTheDocument();
+  });
+
+  it("still renders an explicitly enabled group on a static map", async () => {
+    render(
+      <MapCanvas interactive={false}>
+        <MapControls showFullscreen />
+      </MapCanvas>,
+    );
+    expect(await screen.findByRole("button", { name: "Toggle fullscreen" })).toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "Zoom in" })).not.toBeInTheDocument();
+  });
+
   it("renders compass, locate and fullscreen controls when enabled", async () => {
     render(
       <MapCanvas>
@@ -53,4 +88,113 @@ describe("MapControls", () => {
     await user.click(await screen.findByRole("button", { name: "Zoom in" }));
     expect(MockMap.instances[0]!.zoomToCalls.length).toBeGreaterThan(0);
   });
+
+  it("takes every label from the locale seam, so an app can translate them", async () => {
+    render(
+      <LocaleProvider
+        locale="de-DE"
+        messages={{
+          "maps.controls.zoomIn": "Hineinzoomen",
+          "maps.controls.zoomOut": "Herauszoomen",
+          "maps.controls.resetBearing": "Nach Norden ausrichten",
+          "maps.controls.locate": "Meinen Standort finden",
+          "maps.controls.fullscreen": "Vollbild umschalten",
+          "maps.controls.fit": "Ganzen Plan zeigen",
+        }}
+      >
+        <MapCanvas plan={{ width: 100, height: 50 }}>
+          <MapControls showCompass showLocate showFullscreen />
+        </MapCanvas>
+      </LocaleProvider>,
+    );
+
+    for (const name of [
+      "Hineinzoomen",
+      "Herauszoomen",
+      "Nach Norden ausrichten",
+      "Meinen Standort finden",
+      "Ganzen Plan zeigen",
+      "Vollbild umschalten",
+    ]) {
+      expect(await screen.findByRole("button", { name })).toBeInTheDocument();
+    }
+  });
+});
+
+describe("MapControls fit button", () => {
+  it("stays off a geographic map and appears on a plan", async () => {
+    const { unmount } = render(
+      <MapCanvas>
+        <MapControls />
+      </MapCanvas>,
+    );
+    expect(await screen.findByRole("button", { name: "Zoom in" })).toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "Fit the whole plan" })).not.toBeInTheDocument();
+    unmount();
+
+    render(
+      <MapCanvas plan={{ width: 100, height: 50 }}>
+        <MapControls />
+      </MapCanvas>,
+    );
+    expect(await screen.findByRole("button", { name: "Fit the whole plan" })).toBeInTheDocument();
+  });
+
+  it("frames the plan's own extent and reports back", async () => {
+    const user = userEvent.setup();
+    const onFit = vi.fn();
+    render(
+      <MapCanvas plan={{ width: 100, height: 50 }}>
+        <MapControls onFit={onFit} />
+      </MapCanvas>,
+    );
+
+    const map = MockMap.instances[0]!;
+    const before = map.fitBoundsCalls.length;
+    await user.click(await screen.findByRole("button", { name: "Fit the whole plan" }));
+
+    expect(map.fitBoundsCalls.length).toBe(before + 1);
+    expect(map.fitBoundsCalls.at(-1)!.options).toMatchObject({ padding: 24 });
+    expect(onFit).toHaveBeenCalledTimes(1);
+  });
+
+  it("frames caller bounds when they are given", async () => {
+    const user = userEvent.setup();
+    const bounds: [[number, number], [number, number]] = [
+      [-1, -2],
+      [3, 4],
+    ];
+    render(
+      <MapCanvas plan={{ width: 100, height: 50 }}>
+        <MapControls fitBounds={bounds} />
+      </MapCanvas>,
+    );
+
+    const map = MockMap.instances[0]!;
+    await user.click(await screen.findByRole("button", { name: "Fit the whole plan" }));
+
+    expect(map.fitBoundsCalls.at(-1)!.bounds).toEqual(bounds);
+  });
+
+  // A static plan map drops the zoom chrome but still needs the fit button: it is
+  // the only way back for a reader who cannot pan.
+  it("survives a static plan map, where the zoom chrome is gone", async () => {
+    render(
+      <MapCanvas interactive={false} plan={{ width: 100, height: 50 }}>
+        <MapControls />
+      </MapCanvas>,
+    );
+    expect(await screen.findByRole("button", { name: "Fit the whole plan" })).toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "Zoom in" })).not.toBeInTheDocument();
+  });
+
+  it("can be turned off on a plan", async () => {
+    render(
+      <MapCanvas plan={{ width: 100, height: 50 }}>
+        <MapControls showFit={false} />
+      </MapCanvas>,
+    );
+    expect(await screen.findByRole("button", { name: "Zoom in" })).toBeInTheDocument();
+    expect(screen.queryByRole("button", { name: "Fit the whole plan" })).not.toBeInTheDocument();
+  });
 });

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

@@ -1,16 +1,21 @@
 "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 { Locate, Maximize, Minus, Plus, Scan } from "lucide-react";
+import { Spinner, useLocale } from "@elabs-ai/components-ui";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
 
+import { useMapFrame } from "../lib/use-map-breakpoint";
 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). */
+  /**
+   * Show zoom in/out buttons. Default: true on an interactive map, false on a
+   * static one (`<MapCanvas interactive={false}>`), whose whole point is a
+   * fixed view — set `showZoom` explicitly to override either way.
+   */
   showZoom?: boolean;
   /** Show a compass button to reset bearing/pitch (default: false). */
   showCompass?: boolean;
@@ -18,6 +23,18 @@ export interface MapControlsProps {
   showLocate?: boolean;
   /** Show a fullscreen toggle button (default: false). */
   showFullscreen?: boolean;
+  /**
+   * Show a button that frames the whole plan again — a plan map has an edge to
+   * come back to, so this defaults to ON there and off on a geographic map.
+   */
+  showFit?: boolean;
+  /**
+   * What the fit button frames. Defaults to the plan's own extent; pass bounds
+   * to frame something else (one wing, the selected cluster).
+   */
+  fitBounds?: [[number, number], [number, number]];
+  /** Called after the camera has been asked to frame the plan. */
+  onFit?: () => void;
   /** Additional CSS classes for the controls container. */
   className?: string;
   /** Callback with user coordinates when located. */
@@ -74,16 +91,26 @@ function ControlButton({
 /** Branded zoom / compass / locate / fullscreen controls. Render inside `<MapCanvas>`. */
 export function MapControls({
   position = "bottom-right",
-  showZoom = true,
+  showZoom,
   showCompass = false,
   showLocate = false,
   showFullscreen = false,
+  showFit,
+  fitBounds,
   className,
   onLocate,
   onLocateError,
+  onFit,
 }: MapControlsProps) {
-  const { map } = useMap();
+  const { map, plan } = useMap();
+  const { t } = useLocale();
+  const { interactive } = useMapFrame();
+  // A static map (`interactive={false}`) is a fixed editorial view: zoom chrome
+  // invites a gesture the map will not answer, and a click leaves the reader on
+  // a frame they cannot pan back from. The host may still ask for it.
+  const zoomVisible = showZoom ?? interactive;
   const [waitingForLocation, setWaitingForLocation] = useState(false);
+  const fitVisible = showFit ?? plan != null;
 
   const handleZoomIn = useCallback(() => {
     map?.zoomTo(map.getZoom() + 1, { duration: 300 });
@@ -121,6 +148,13 @@ export function MapControls({
     );
   }, [map, onLocate, onLocateError]);
 
+  const handleFit = useCallback(() => {
+    const bounds = fitBounds ?? plan?.bounds;
+    if (!map || !bounds) return;
+    map.fitBounds(bounds, { padding: 24, duration: 300 });
+    onFit?.();
+  }, [fitBounds, map, onFit, plan]);
+
   const handleFullscreen = useCallback(() => {
     const container = map?.getContainer();
     if (!container) return;
@@ -131,16 +165,19 @@ export function MapControls({
     }
   }, [map]);
 
+  // Nothing to show (a static map with no explicit group) renders no box at all.
+  if (!zoomVisible && !fitVisible && !showCompass && !showLocate && !showFullscreen) return null;
+
   return (
     <div
       className={cn("absolute z-10 flex flex-col gap-1.5", positionClasses[position], className)}
     >
-      {showZoom && (
+      {zoomVisible && (
         <ControlGroup>
-          <ControlButton onClick={handleZoomIn} label="Zoom in">
+          <ControlButton onClick={handleZoomIn} label={t("maps.controls.zoomIn")}>
             <Plus className="size-4" aria-hidden="true" />
           </ControlButton>
-          <ControlButton onClick={handleZoomOut} label="Zoom out">
+          <ControlButton onClick={handleZoomOut} label={t("maps.controls.zoomOut")}>
             <Minus className="size-4" aria-hidden="true" />
           </ControlButton>
         </ControlGroup>
@@ -154,20 +191,27 @@ export function MapControls({
         <ControlGroup>
           <ControlButton
             onClick={handleLocate}
-            label="Find my location"
+            label={t("maps.controls.locate")}
             disabled={waitingForLocation}
           >
             {waitingForLocation ? (
-              <Spinner label="Locating" className="size-4 text-foreground" />
+              <Spinner label={t("maps.controls.locating")} className="size-4 text-foreground" />
             ) : (
               <Locate className="size-4" aria-hidden="true" />
             )}
           </ControlButton>
         </ControlGroup>
       )}
+      {fitVisible && (
+        <ControlGroup>
+          <ControlButton onClick={handleFit} label={t("maps.controls.fit")}>
+            <Scan className="size-4" aria-hidden="true" />
+          </ControlButton>
+        </ControlGroup>
+      )}
       {showFullscreen && (
         <ControlGroup>
-          <ControlButton onClick={handleFullscreen} label="Toggle fullscreen">
+          <ControlButton onClick={handleFullscreen} label={t("maps.controls.fullscreen")}>
             <Maximize className="size-4" aria-hidden="true" />
           </ControlButton>
         </ControlGroup>
@@ -178,6 +222,7 @@ export function MapControls({
 
 function CompassButton({ onClick }: { onClick: () => void }) {
   const { map } = useMap();
+  const { t } = useLocale();
   const compassRef = useRef<SVGSVGElement>(null);
 
   useEffect(() => {
@@ -202,7 +247,7 @@ function CompassButton({ onClick }: { onClick: () => void }) {
   }, [map]);
 
   return (
-    <ControlButton onClick={onClick} label="Reset bearing to north">
+    <ControlButton onClick={onClick} label={t("maps.controls.resetBearing")}>
       <svg
         ref={compassRef}
         viewBox="0 0 24 24"

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

@@ -1,8 +1,10 @@
 import { useEffect, useState } from "react";
 import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, waitFor } from "storybook/test";
 import { resolveTokenColor } from "@elabs-ai/components-tokens";
 
-import { MapCanvas } from "../map-canvas";
+import { MapCanvas, type MapCanvasRef } from "../map-canvas";
+import { GREATER_TORONTO, LAKE_ONTARIO, LOCATOR_BOUNDS } from "../test-utils/locator-fixture";
 import { MapGeoJSON } from "./map-geojson";
 
 /**
@@ -64,6 +66,39 @@ function makeRegions(): GeoJSON.FeatureCollection<GeoJSON.Polygon, RegionProps>
 
 const regions = makeRegions();
 
+/**
+ * The regions' own extent, as `[[west, south], [east, north]]` (c-9). A fixed
+ * `center`/`zoom` framed the grid for a wide box only: at 380 px two of the six
+ * columns fell outside the map with no edge cue and no way to pan a static map
+ * back to them. Fitting the data keeps every region inside the box at every
+ * width, exactly as the `PatternAndVignette` story already does.
+ */
+function boundsOf(
+  collection: GeoJSON.FeatureCollection<GeoJSON.Polygon, RegionProps>,
+): [[number, number], [number, number]] {
+  let west = Infinity,
+    south = Infinity,
+    east = -Infinity,
+    north = -Infinity;
+  for (const feature of collection.features) {
+    for (const ring of feature.geometry.coordinates) {
+      for (const [lng, lat] of ring) {
+        west = Math.min(west, lng);
+        east = Math.max(east, lng);
+        south = Math.min(south, lat);
+        north = Math.max(north, lat);
+      }
+    }
+  }
+  return [
+    [west, south],
+    [east, north],
+  ];
+}
+
+const REGION_BOUNDS = boundsOf(regions);
+const REGION_FIT = { padding: 16 };
+
 const meta = {
   title: "Maps/MapGeoJSON",
   component: MapGeoJSON,
@@ -73,15 +108,68 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
+/** The map the framing assertion below measures. */
+let framedMap: MapCanvasRef | null = null;
+
 /** 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}>
+      <MapCanvas
+        blank
+        bounds={REGION_BOUNDS}
+        fitBoundsOptions={REGION_FIT}
+        ref={(map) => {
+          framedMap = map;
+        }}
+      >
         <MapGeoJSON data={regions} />
       </MapCanvas>
     </div>
   ),
+  play: async ({ canvasElement }) => {
+    // c-9: at phone width the fixed `center`/`zoom` put two of the six region
+    // columns outside the box — 38.7 % of the data's area, with no edge cue,
+    // no scale change and no message, on a map nobody can pan. Squeeze the
+    // box to the reviewer's 380 px and check every corner of the data is
+    // still painted inside it.
+    const box = canvasElement.querySelector<HTMLElement>("div");
+    if (!box) throw new Error("the story's map box is missing");
+    box.style.width = "380px";
+
+    const [[west, south], [east, north]] = REGION_BOUNDS;
+    await waitFor(
+      () => {
+        const map = framedMap;
+        expect(map).not.toBeNull();
+        const canvas = map!.getContainer().getBoundingClientRect();
+        expect(Math.round(canvas.width)).toBe(380);
+        for (const corner of [
+          [west, south],
+          [east, south],
+          [east, north],
+          [west, north],
+        ] as [number, number][]) {
+          const point = map!.project(corner);
+          expect(point.x).toBeGreaterThanOrEqual(0);
+          expect(point.x).toBeLessThanOrEqual(canvas.width);
+          expect(point.y).toBeGreaterThanOrEqual(0);
+          expect(point.y).toBeLessThanOrEqual(canvas.height);
+        }
+      },
+      { timeout: 8000 },
+    );
+    // Hand the story back its own width — a play runs in the dev Storybook
+    // too — and check the map re-frames itself on the way back out.
+    box.style.width = "";
+    await waitFor(() => {
+      const canvas = framedMap!.getContainer().getBoundingClientRect();
+      expect(Math.round(canvas.width)).toBeGreaterThan(380);
+      const point = framedMap!.project([east, north]);
+      expect(point.x).toBeLessThanOrEqual(canvas.width);
+      expect(point.x).toBeGreaterThanOrEqual(0);
+    });
+  },
 };
 
 function ChoroplethDemo() {
@@ -91,7 +179,7 @@ function ChoroplethDemo() {
   const primary = useThemedTokenColor("--primary");
   return (
     <div className="relative h-[480px]">
-      <MapCanvas blank center={[10, 48]} zoom={3.2}>
+      <MapCanvas blank bounds={REGION_BOUNDS} fitBoundsOptions={REGION_FIT}>
         <MapGeoJSON<RegionProps>
           data={regions}
           promoteId="name"
@@ -109,6 +197,12 @@ function ChoroplethDemo() {
             ] as never,
           }}
           fillHoverPaint={{ "fill-opacity": 1 }}
+          // c-2: the fill lives in WebGL, so without this the 24 values are
+          // reachable by mouse only. One visually-hidden button per region
+          // carries the same sentence the readout prints.
+          featureLabel={(feature) =>
+            `${feature.properties.name}: ${(feature.properties.value * 100).toFixed(0)}%`
+          }
           onHover={(e) => setHovered(e?.feature.properties ?? null)}
         />
       </MapCanvas>
@@ -121,4 +215,60 @@ function ChoroplethDemo() {
 
 export const InteractiveHover: Story = {
   render: () => <ChoroplethDemo />,
+  play: async ({ canvasElement }) => {
+    // c-2 (WCAG 2.1.1 / 1.3.1): before the fix the only tab stop in the story
+    // was the map canvas, and none of the 24 region values had any DOM at all.
+    const list = await waitFor(() => {
+      const element = canvasElement.querySelector('[data-slot="map-geojson-keyboard-list"]');
+      expect(element).not.toBeNull();
+      return element as HTMLElement;
+    });
+    const buttons = [...list.querySelectorAll("button")];
+    await expect(buttons).toHaveLength(24);
+    await expect(buttons[0]).toHaveAccessibleName("Region 1: 37%");
+
+    // Focusing a region updates the very readout the pointer drives.
+    buttons[9]?.focus();
+    await waitFor(() =>
+      expect(canvasElement.textContent).toContain(
+        buttons[9]?.textContent ?? "no region under focus",
+      ),
+    );
+  },
+};
+
+function AreaMarkersDemo() {
+  const lake = useThemedTokenColor("--chart-1");
+  const region = useThemedTokenColor("--chart-2");
+  return (
+    <div className="w-full p-4">
+      <MapCanvas interactive={false} bounds={LOCATOR_BOUNDS} fitBoundsOptions={{ padding: 32 }}>
+        <MapGeoJSON
+          id="gta"
+          data={GREATER_TORONTO}
+          fillPaint={{ "fill-color": region }}
+          fillOpacity={0.3}
+          vignette={{ width: 10, opacity: 0.4 }}
+          linePaint={false}
+        />
+        <MapGeoJSON
+          id="lake"
+          data={LAKE_ONTARIO}
+          fillPaint={{ "fill-color": lake }}
+          pattern={{ kind: "stripes", width: 2, gap: 4 }}
+          vignette={{ width: 14, opacity: 0.35 }}
+          linePaint={{ "line-color": lake, "line-width": 1 }}
+        />
+      </MapCanvas>
+    </div>
+  );
+}
+
+/**
+ * Area markers for a locator: a striped fill (a second channel besides
+ * colour — it survives greyscale) and a soft vignette glow along the edge.
+ * `fillOpacity` sets the tint under the stripes.
+ */
+export const PatternAndVignette: Story = {
+  render: () => <AreaMarkersDemo />,
 };