@elabs-ai/components-maps 4.2.0 → 5.0.0

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

@@ -0,0 +1,136 @@
+import { cleanup, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { colorScaleFor } from "@elabs-ai/components-ui";
+
+vi.mock("maplibre-gl", async () => {
+  const { createMaplibreMock } = await import("../test-utils/maplibre-mock");
+  return createMaplibreMock();
+});
+
+import { resetMaplibreMock } from "../test-utils/maplibre-mock";
+import { MapCanvas } from "../map-canvas";
+import { MapLegend } from "./map-legend";
+
+afterEach(() => {
+  cleanup();
+  resetMaplibreMock();
+});
+
+const VALUES = [3, 8, 12, 19, 25, 31, 44, 52, 60];
+
+describe("MapLegend", () => {
+  it("renders marker rows with their swatches, over a corner", async () => {
+    render(
+      <MapCanvas>
+        <MapLegend
+          title="Markers"
+          position="top-left"
+          items={[
+            { label: "Lake", color: "var(--chart-1)", shape: "square" },
+            { label: "City", color: "var(--chart-2)" },
+          ]}
+        />
+      </MapCanvas>,
+    );
+    expect(await screen.findByText("Lake")).toBeInTheDocument();
+    const legend = document.querySelector<HTMLElement>('[data-slot="map-legend"]')!;
+    expect(legend).toHaveAttribute("data-position", "top-left");
+    // Inside the map box, over the corner.
+    expect(document.querySelector('[data-slot="map-canvas"]')!.contains(legend)).toBe(true);
+    const swatches = legend.querySelectorAll<HTMLElement>('[data-slot="map-legend-swatch"]');
+    expect([...swatches].map((s) => s.dataset.shape)).toEqual(["square", "circle"]);
+  });
+
+  it("portals into the strip below the map when positioned below", async () => {
+    render(
+      <MapCanvas>
+        <MapLegend position="below" items={[{ label: "Lake", color: "var(--chart-1)" }]} />
+      </MapCanvas>,
+    );
+    await screen.findByText("Lake");
+    const legend = document.querySelector('[data-slot="map-legend"]')!;
+    expect(document.querySelector('[data-slot="map-canvas-below"]')!.contains(legend)).toBe(true);
+    expect(document.querySelector('[data-slot="map-canvas"]')!.contains(legend)).toBe(false);
+  });
+
+  it("keys a stepped scale with token-reference swatches only", async () => {
+    render(
+      <MapCanvas>
+        <MapLegend scale={{ values: VALUES, spec: { type: "stepped", steps: 4 } }} />
+      </MapCanvas>,
+    );
+    await waitFor(() =>
+      expect(document.querySelectorAll('[data-slot="map-legend-step"]')).toHaveLength(4),
+    );
+    const steps = document.querySelectorAll<HTMLElement>('[data-slot="map-legend-step"]');
+    for (const step of steps) {
+      expect(step.getAttribute("style")).toMatch(/^background: var\(--chart-seq-\d\);$/);
+    }
+    // 4 steps → 5 boundary ticks.
+    expect(document.querySelectorAll('[data-slot="map-legend-tick"]')).toHaveLength(5);
+  });
+
+  it("draws a continuous scale as a gradient of token references", async () => {
+    const scale = colorScaleFor(VALUES, { type: "continuous" });
+    render(
+      <MapCanvas>
+        <MapLegend scale={scale} formatValue={(v) => `${v}%`} />
+      </MapCanvas>,
+    );
+    const gradient = await waitFor(() => {
+      const el = document.querySelector<HTMLElement>('[data-slot="map-legend-gradient"]');
+      expect(el).not.toBeNull();
+      return el!;
+    });
+    const style = gradient.getAttribute("style") ?? "";
+    expect(style).toContain("linear-gradient(to right, var(--chart-seq-1) 0%");
+    expect(style).not.toMatch(/#[0-9a-f]{3,8}\b|rgb\(|oklch\(/i);
+    expect(screen.getByText("3%")).toBeInTheDocument();
+    expect(screen.getByText("60%")).toBeInTheDocument();
+  });
+
+  it("lists a categorical scale as swatch rows", async () => {
+    render(
+      <MapCanvas>
+        <MapLegend
+          scale={{
+            values: ["Park", "Water", "Park"],
+            spec: { type: "stepped", palette: "categorical" },
+          }}
+        />
+      </MapCanvas>,
+    );
+    expect(await screen.findByText("Park")).toBeInTheDocument();
+    expect(screen.getByText("Water")).toBeInTheDocument();
+    expect(document.querySelector('[data-slot="map-legend-ramp"]')).toBeNull();
+  });
+});
+
+describe("MapLegend — a grid key spends the whole strip (c-5)", () => {
+  it("lays the grid out with auto-fit, so empty tracks collapse", async () => {
+    render(
+      <MapCanvas>
+        <MapLegend
+          layout="grid"
+          items={[
+            { id: "lake", label: "Lake Ontario", color: "var(--chart-1)", shape: "square" },
+            { id: "gta", label: "Greater Toronto Area", color: "var(--chart-2)", shape: "square" },
+            { id: "city", label: "City", color: "var(--chart-4)", shape: "circle" },
+            { id: "ferry", label: "Ferry route", color: "var(--chart-3)", shape: "line" },
+          ]}
+        />
+      </MapCanvas>,
+    );
+    const list = await waitFor(() => {
+      const found = document.querySelector('[data-slot="map-legend-items"]');
+      expect(found).not.toBeNull();
+      return found!;
+    });
+    // `auto-fill` kept 7 tracks of 113.7 px on an 868 px strip for four keys,
+    // so "Greater Toronto Area" truncated (scrollWidth 123 vs clientWidth 98)
+    // with three empty tracks beside it. jsdom lays out nothing, so the
+    // measured proof lives in the story; this locks the layout rule itself.
+    expect(list.className).toContain("repeat(auto-fit,minmax(7rem,1fr))");
+    expect(list.className).not.toContain("auto-fill");
+  });
+});

package/src/map-legend/map-legend.tsx

@@ -0,0 +1,264 @@
+"use client";
+
+import { forwardRef, useMemo, type HTMLAttributes, type ReactNode } from "react";
+import { createPortal } from "react-dom";
+import {
+  colorScaleFor,
+  useLocale,
+  type ColorScale,
+  type ColorScaleSpec,
+  type ColorScaleValue,
+} from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+
+import { type MapResponsive, useMapFrameSlot, useMapResponsive } from "../lib/use-map-breakpoint";
+import { MAP_CORNER_CLASSES, type MapCorner } from "./map-corner";
+
+/** The mark a key row shows: a point, an area or a line marker. */
+export type MapLegendShape = "circle" | "square" | "line";
+
+/** One row of a marker key. */
+export interface MapLegendItem {
+  /** Stable identity; defaults to `label`. */
+  id?: string;
+  label: string;
+  /** Any CSS colour — use a token reference (`var(--chart-1)`), never a literal. */
+  color: string;
+  /** Default `"circle"`. */
+  shape?: MapLegendShape;
+}
+
+/**
+ * A colour scale to key: one `colorScaleFor` already built (share it with the
+ * layer it colours), or the values + spec to build one here.
+ */
+export type MapLegendScale =
+  | ColorScale
+  | { values: readonly ColorScaleValue[]; spec: ColorScaleSpec };
+
+/** Outside the map box (`above` / `below`) or over one of its corners. */
+export type MapLegendPosition = "above" | "below" | MapCorner;
+
+/** `list`: one row per item. `grid`: items flow into as many columns as fit. */
+export type MapLegendLayout = "list" | "grid";
+
+export interface MapLegendProps extends Omit<HTMLAttributes<HTMLDivElement>, "title"> {
+  /** A heading for the key. */
+  title?: ReactNode;
+  /** Marker key rows. */
+  items?: readonly MapLegendItem[];
+  /** A colour ramp (continuous / stepped) or category key, from `colorScaleFor`. */
+  scale?: MapLegendScale;
+  /** Default `"list"`. */
+  layout?: MapLegendLayout;
+  /**
+   * Where the key sits, optionally per tier — for example
+   * `{ base: "top-left", narrow: "below" }` so it stops covering a phone-width
+   * map. Default `"above"`.
+   */
+  position?: MapResponsive<MapLegendPosition>;
+  /** Formats a ramp's tick values (default: the locale's number format). */
+  formatValue?: (value: number) => string;
+}
+
+const SHAPE_CLASSES: Record<MapLegendShape, string> = {
+  circle: "size-2.5 rounded-full",
+  square: "size-2.5 rounded-xs",
+  line: "h-0.5 w-3.5 rounded-full",
+};
+
+const LAYOUT_CLASSES: Record<MapLegendLayout, string> = {
+  list: "flex flex-col gap-1",
+  // `auto-fit`, never `auto-fill` (c-5): `auto-fill` keeps the tracks a wide
+  // strip could hold even when nothing occupies them, so four keys on an
+  // 868 px strip got 113.7 px each and "Greater Toronto Area" truncated with
+  // three empty tracks beside it. `auto-fit` collapses the empty tracks and
+  // the real keys share the full width; a key with more items than fit wraps
+  // exactly as before.
+  grid: "grid grid-cols-[repeat(auto-fit,minmax(7rem,1fr))] gap-x-3 gap-y-1",
+};
+
+function isColorScale(scale: MapLegendScale): scale is ColorScale {
+  return "colorOf" in scale;
+}
+
+function Swatch({ color, shape = "circle" }: { color: string; shape?: MapLegendShape }) {
+  return (
+    <span
+      aria-hidden="true"
+      data-slot="map-legend-swatch"
+      data-shape={shape}
+      className={cn("inline-block shrink-0", SHAPE_CLASSES[shape])}
+      style={{ background: color }}
+    />
+  );
+}
+
+interface Tick {
+  key: string;
+  at: number;
+  label: string;
+}
+
+/** A ramp: stepped swatches or a continuous gradient, with value ticks under it. */
+function Ramp({ scale, format }: { scale: ColorScale; format: (value: number) => string }) {
+  const ticks: Tick[] = [];
+  let strip: ReactNode = null;
+
+  if (scale.type === "stepped" && scale.steps.length > 0) {
+    const n = scale.steps.length;
+    strip = (
+      <div className="flex h-2.5 w-full overflow-hidden rounded-xs">
+        {scale.steps.map((step) => (
+          <span
+            key={`${step.from}-${step.to}`}
+            data-slot="map-legend-step"
+            className="min-w-0 flex-1"
+            style={{ background: step.color }}
+          />
+        ))}
+      </div>
+    );
+    const first = scale.steps[0];
+    if (first) ticks.push({ key: "start", at: 0, label: format(first.from) });
+    scale.steps.forEach((step, index) => {
+      ticks.push({ key: `to-${step.to}`, at: (index + 1) / n, label: format(step.to) });
+    });
+  } else if (scale.stops.length > 0) {
+    const last = Math.max(1, scale.stops.length - 1);
+    const gradient = scale.stops
+      .map((stop, index) => `${stop.color} ${(index / last) * 100}%`)
+      .join(", ");
+    strip = (
+      <div
+        data-slot="map-legend-gradient"
+        className="h-2.5 w-full rounded-xs"
+        style={{ background: `linear-gradient(to right, ${gradient})` }}
+      />
+    );
+    const marks = [scale.domain?.[0], scale.center ?? undefined, scale.domain?.[1]];
+    for (const value of marks) {
+      if (value === undefined) continue;
+      const at = scale.positionOf(value);
+      if (at === null) continue;
+      ticks.push({ key: `v-${value}`, at, label: format(value) });
+    }
+  }
+
+  if (!strip) return null;
+  return (
+    // A ramp reads low → high left to right in every writing direction.
+    <div dir="ltr" data-slot="map-legend-ramp" className="flex w-48 max-w-full flex-col gap-1">
+      {strip}
+      <div className="relative h-4">
+        {ticks.map((tick) => (
+          <span
+            key={tick.key}
+            data-slot="map-legend-tick"
+            className={cn(
+              "absolute top-0 text-meta whitespace-nowrap text-muted-foreground tabular-nums",
+              tick.at <= 0 ? "" : tick.at >= 1 ? "-translate-x-full" : "-translate-x-1/2",
+            )}
+            style={{ left: `${Math.min(1, Math.max(0, tick.at)) * 100}%` }}
+          >
+            {tick.label}
+          </span>
+        ))}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * MapLegend — the map's key: marker rows (`items`) and / or a colour ramp
+ * (`scale`, built with `colorScaleFor` from `@elabs-ai/components-ui`, so its
+ * colours are token references in every theme). It sits above or below the
+ * map box, or over a corner, per tier; the house legend look (`text-meta`,
+ * dot markers) matches `charts`' `ChartLegend`. Render inside `<MapCanvas>`.
+ */
+export const MapLegend = forwardRef<HTMLDivElement, MapLegendProps>(function MapLegend(
+  {
+    title,
+    items,
+    scale: scaleInput,
+    layout = "list",
+    position: positionProp = "above",
+    formatValue,
+    className,
+    ...props
+  },
+  ref,
+) {
+  const { formatNumber } = useLocale();
+  const position = useMapResponsive(positionProp);
+  const outside = position === "above" || position === "below" ? position : null;
+  const slot = useMapFrameSlot(outside);
+
+  const scale = useMemo<ColorScale | null>(() => {
+    if (!scaleInput) return null;
+    return isColorScale(scaleInput)
+      ? scaleInput
+      : colorScaleFor(scaleInput.values, scaleInput.spec);
+  }, [scaleInput]);
+  const format = formatValue ?? ((value: number) => formatNumber(value));
+
+  const rows: MapLegendItem[] = [
+    ...(items ?? []),
+    ...(scale?.palette === "categorical"
+      ? scale.categories.map((category) => ({
+          id: `category-${category.value}`,
+          label: String(category.value),
+          color: category.color,
+          shape: "square" as const,
+        }))
+      : []),
+  ];
+  const showRamp = scale !== null && scale.palette !== "categorical";
+
+  const body = (
+    <div
+      ref={ref}
+      data-slot="map-legend"
+      data-position={position}
+      data-layout={layout}
+      className={cn(
+        "flex flex-col gap-1.5 text-meta text-foreground",
+        outside
+          ? "w-full"
+          : cn(
+              "absolute z-10 max-w-[calc(100%-1rem)] rounded-md bg-background/90 px-2 py-1.5 shadow-ring-sm",
+              MAP_CORNER_CLASSES[position as MapCorner],
+            ),
+        className,
+      )}
+      {...props}
+    >
+      {title && (
+        <div data-slot="map-legend-title" className="font-medium">
+          {title}
+        </div>
+      )}
+      {rows.length > 0 && (
+        <ul
+          data-slot="map-legend-items"
+          className={cn("m-0 list-none p-0", LAYOUT_CLASSES[layout])}
+        >
+          {rows.map((item) => (
+            <li
+              key={item.id ?? item.label}
+              data-slot="map-legend-item"
+              className="flex min-w-0 items-center gap-1.5"
+            >
+              <Swatch color={item.color} shape={item.shape} />
+              <span className="min-w-0 truncate">{item.label}</span>
+            </li>
+          ))}
+        </ul>
+      )}
+      {showRamp && scale && <Ramp scale={scale} format={format} />}
+    </div>
+  );
+
+  if (outside) return slot ? createPortal(body, slot) : null;
+  return body;
+});

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

@@ -1,7 +1,10 @@
 import type { Meta, StoryObj } from "@storybook/react-vite";
 import { MapPin } from "lucide-react";
+import { expect, waitFor } from "storybook/test";
 
 import { MapCanvas } from "../map-canvas";
+import { MAP_LABEL_ANCHORS } from "../map-annotation";
+import { LOCATOR_BOUNDS, LOCATOR_PLACES } from "../test-utils/locator-fixture";
 import {
   MapMarker,
   MapMarkerContent,
@@ -32,11 +35,24 @@ export const Default: Story = {
   ),
 };
 
+/** Both markers, with room for the wider label under the second one (c-8). */
+const ALEXANDERPLATZ: [number, number] = [13.405, 52.52];
+const BRANDENBURG_GATE: [number, number] = [13.377, 52.516];
+
 export const WithPopupAndTooltip: Story = {
   render: () => (
     <div className="h-[480px]">
-      <MapCanvas center={[13.41, 52.52]} zoom={12}>
-        <MapMarker longitude={13.405} latitude={52.52}>
+      {/*
+        c-8: a fixed center/zoom framed both markers at 900 px only — at
+        380 px the second marker sat half off the start edge and its label
+        read "…urg Gate". Fitting the markers keeps both inside at every
+        width; the padding is the room the wider label needs.
+      */}
+      <MapCanvas
+        bounds={[BRANDENBURG_GATE, ALEXANDERPLATZ]}
+        fitBoundsOptions={{ padding: 72, maxZoom: 14 }}
+      >
+        <MapMarker longitude={ALEXANDERPLATZ[0]} latitude={ALEXANDERPLATZ[1]}>
           <MapMarkerContent />
           <MapMarkerTooltip>Click for details</MapMarkerTooltip>
           <MapMarkerPopup closeButton>
@@ -46,7 +62,7 @@ export const WithPopupAndTooltip: Story = {
             </p>
           </MapMarkerPopup>
         </MapMarker>
-        <MapMarker longitude={13.377} latitude={52.516}>
+        <MapMarker longitude={BRANDENBURG_GATE[0]} latitude={BRANDENBURG_GATE[1]}>
           <MapMarkerContent>
             <MapPin className="size-6 text-primary" aria-hidden="true" />
           </MapMarkerContent>
@@ -61,11 +77,127 @@ 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>
+        <MapMarker longitude={13.405} latitude={52.52} draggable dragLabel="Depot location">
           <MapMarkerContent />
           <MapMarkerLabel>Drag me</MapMarkerLabel>
         </MapMarker>
       </MapCanvas>
     </div>
   ),
+  play: async ({ canvasElement }) => {
+    // c-4 (WCAG 2.1.1): the story's whole subject is a marker you move, so it
+    // has to be movable without a mouse. Before the fix the only tab stop in
+    // the story was the map canvas and `element.focus()` did not take.
+    const marker = await waitFor(() => {
+      const element = canvasElement.querySelector<HTMLElement>(".maplibregl-marker");
+      expect(element).not.toBeNull();
+      return element as HTMLElement;
+    });
+    await expect(marker).toHaveAttribute("tabindex", "0");
+    await expect(marker).toHaveAccessibleName("Depot location");
+
+    marker.focus();
+    await expect(document.activeElement).toBe(marker);
+
+    const before = marker.getBoundingClientRect().x;
+    marker.dispatchEvent(new KeyboardEvent("keydown", { key: "ArrowRight", bubbles: true }));
+    marker.dispatchEvent(new KeyboardEvent("keyup", { key: "ArrowRight", bubbles: true }));
+    await waitFor(() => expect(marker.getBoundingClientRect().x).toBeGreaterThan(before));
+  },
+};
+
+// A marker's own label has no de-confliction pass: it goes where its anchor
+// puts it, however close the next marker is. The boxed row's labels offset
+// OUTWARD from their point, so at the narrow tier — where a degree of
+// longitude is ~100px and a boxed label is up to 71px wide — two neighbours
+// print on top of each other. That row is therefore shown from `medium` up
+// (`showAt`), which is the prop the docblock already points at.
+const LABEL_SPOTS = [
+  { longitude: -79.6, latitude: 44.05 },
+  { longitude: -78.6, latitude: 44.05 },
+  { longitude: -77.6, latitude: 44.05 },
+  { longitude: -76.6, latitude: 44.05 },
+  { longitude: -79.6, latitude: 43.45 },
+  { longitude: -78.6, latitude: 43.45 },
+  { longitude: -77.6, latitude: 43.45 },
+  { longitude: -76.6, latitude: 43.45 },
+] as const;
+
+/**
+ * A marker's own label, at each of the eight positions around its point;
+ * the lower row adds a box (a plate that keeps the text readable over busy
+ * ground) and a callout line.
+ */
+export const LabelPositions: Story = {
+  render: () => (
+    <div className="w-full p-4">
+      <MapCanvas interactive={false} bounds={LOCATOR_BOUNDS} fitBoundsOptions={{ padding: 48 }}>
+        {MAP_LABEL_ANCHORS.map((position, index) => (
+          <MapMarker
+            key={position}
+            {...LABEL_SPOTS[index]!}
+            label={{ text: position, position, box: index >= 4, callout: index >= 4 }}
+            showAt={index >= 4 ? { base: true, narrow: false } : true}
+          >
+            <MapMarkerContent />
+          </MapMarker>
+        ))}
+      </MapCanvas>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    // Two labels printed through each other read as neither. Measured, per
+    // tier: the boxed row is off at narrow, so every tier comes out clean.
+    await waitFor(() =>
+      expect(
+        canvasElement.querySelectorAll('[data-slot="map-marker-label"]').length,
+      ).toBeGreaterThan(0),
+    );
+    const boxes = [
+      ...canvasElement.querySelectorAll<HTMLElement>('[data-slot="map-marker-label"]'),
+    ].map((el) => el.getBoundingClientRect());
+    const overlaps: string[] = [];
+    for (const [i, a] of boxes.entries()) {
+      for (const b of boxes.slice(i + 1)) {
+        const x = Math.min(a.right, b.right) - Math.max(a.left, b.left);
+        const y = Math.min(a.bottom, b.bottom) - Math.max(a.top, b.top);
+        if (x > 0 && y > 0) overlaps.push(`${Math.round(x * y)}px²`);
+      }
+    }
+    await expect(overlaps).toEqual([]);
+  },
+};
+
+/**
+ * A label with no marker glyph — text placed on the map (a lake or region
+ * name) — plus a marker that only shows from `medium` up.
+ */
+export const LabelOnlyAndShowAt: Story = {
+  render: () => (
+    <div className="w-full p-4">
+      <MapCanvas interactive={false} bounds={LOCATOR_BOUNDS} fitBoundsOptions={{ padding: 48 }}>
+        <MapMarker {...LOCATOR_PLACES.lakeLabel} label={{ text: "Lake Ontario", box: true }} />
+        <MapMarker {...LOCATOR_PLACES.toronto} label={{ text: "Toronto", position: "top-left" }}>
+          <MapMarkerContent />
+        </MapMarker>
+        <MapMarker
+          {...LOCATOR_PLACES.rochester}
+          showAt={{ base: true, narrow: false }}
+          label={{ text: "Rochester, NY", position: "right" }}
+        >
+          <MapMarkerContent />
+        </MapMarker>
+      </MapCanvas>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    const map = canvasElement.querySelector<HTMLElement>('[data-slot="map-canvas"]');
+    if (!map || !canvasElement.querySelector(".maplibregl-canvas")) return;
+    const narrow = map.getAttribute("data-map-breakpoint") === "narrow";
+    await waitFor(() =>
+      expect(canvasElement.querySelectorAll('[data-slot="map-marker-label"]')).toHaveLength(
+        narrow ? 2 : 3,
+      ),
+    );
+  },
 };