@elabs-ai/components-maps 4.1.0 → 5.0.0

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

@@ -1,12 +1,35 @@
 "use client";
 
 import MapLibreGL, { type MarkerOptions, type PopupOptions } from "maplibre-gl";
-import { createContext, use, useEffect, useMemo, useRef, type ReactNode } from "react";
+import {
+  createContext,
+  use,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useRef,
+  useState,
+  type ReactNode,
+} from "react";
 import { createPortal } from "react-dom";
 import { X } from "lucide-react";
 import { cn } from "@elabs-ai/components-ui/lib/cn";
+import { useLocale } from "@elabs-ai/components-ui";
 
 import { useMap } from "../map-canvas/map-context";
+import {
+  type MapResponsive,
+  useMapBreakpoint,
+  resolveMapResponsive,
+} from "../lib/use-map-breakpoint";
+import {
+  type MapLabelAnchor,
+  clampShift,
+  mapAnchorGeometry,
+  mapAnchorTransform,
+} from "../map-annotation/anchor";
+import { resolveMapPosition, toPlanPoint, type MapPosition } from "../lib/map-position";
+import type { PlanPoint } from "../lib/plan-crs";
 
 type MarkerContextValue = {
   marker: MapLibreGL.Marker;
@@ -23,35 +46,68 @@ function useMarkerContext() {
   return context;
 }
 
-export type MapMarkerProps = {
-  /** Longitude coordinate for the marker position. */
-  longitude: number;
-  /** Latitude coordinate for the marker position. */
-  latitude: number;
-  /** Marker sub-components (MapMarkerContent, MapMarkerPopup, MapMarkerTooltip, MapMarkerLabel). */
-  children: ReactNode;
+/**
+ * A marker's own text label — the locator-map label: one of eight positions,
+ * optionally on a box, optionally pushed out on a callout line.
+ */
+export interface MapMarkerLabelSpec {
+  /** The label text. */
+  text: string;
+  /** Where the label sits relative to the point (default `"top"`). */
+  position?: MapLabelAnchor;
+  /** Set the label on a background box so it reads over a busy basemap. */
+  box?: boolean;
+  /** Push the label further out and draw a callout line back to the point. */
+  callout?: boolean;
+}
+
+export type MapMarkerProps = MapPosition & {
+  /**
+   * Marker sub-components (MapMarkerContent, MapMarkerPopup, MapMarkerTooltip,
+   * MapMarkerLabel). Optional when `label` alone marks the place — an inline
+   * area label, for example.
+   */
+  children?: ReactNode;
+  /**
+   * Whether the marker shows at a tier (default `true` everywhere):
+   * `{ base: true, narrow: false }` drops it from a phone-width map. The
+   * The editorial advice applies — duplicate a marker with a shorter label and
+   * the opposite `showAt` rather than cramming one label into both.
+   */
+  showAt?: MapResponsive<boolean>;
+  /** A text label drawn with the marker (see {@link MapMarkerLabelSpec}). */
+  label?: MapMarkerLabelSpec;
   /** Callback when the marker is clicked. */
   onClick?: (e: MouseEvent) => void;
   /** Callback when the mouse enters the marker. */
   onMouseEnter?: (e: MouseEvent) => void;
   /** Callback when the mouse leaves the marker. */
   onMouseLeave?: (e: MouseEvent) => void;
-  /** Callback when a drag starts (requires `draggable`). */
-  onDragStart?: (lngLat: { lng: number; lat: number }) => void;
-  /** Callback during a drag (requires `draggable`). */
-  onDrag?: (lngLat: { lng: number; lat: number }) => void;
-  /** Callback when a drag ends (requires `draggable`). */
-  onDragEnd?: (lngLat: { lng: number; lat: number }) => void;
+  /** Callback when a drag starts (requires `draggable`). The plan point is `null` off a plan. */
+  onDragStart?: (lngLat: { lng: number; lat: number }, plan: PlanPoint | null) => void;
+  /** Callback during a drag (requires `draggable`). The plan point is `null` off a plan. */
+  onDrag?: (lngLat: { lng: number; lat: number }, plan: PlanPoint | null) => void;
+  /** Callback when a drag ends (requires `draggable`). The plan point is `null` off a plan. */
+  onDragEnd?: (lngLat: { lng: number; lat: number }, plan: PlanPoint | null) => void;
+  /**
+   * The accessible name of a `draggable` marker — say what it moves ("Depot
+   * location"). Defaults to the locale seam's generic name. Ignored when the
+   * marker is not draggable.
+   */
+  dragLabel?: string;
 } & Omit<MarkerOptions, "element">;
 
 /**
- * A marker anchored at a lng/lat. Compose the pieces you need:
- * `MapMarkerContent` (the visual), `MapMarkerLabel`, `MapMarkerPopup` (opens
- * on click) and `MapMarkerTooltip` (shows on hover).
+ * A marker anchored at a lng/lat — or, on a canvas with a `plan` extent, at a
+ * plan `x`/`y`. Compose the pieces you need: `MapMarkerContent` (the visual),
+ * `MapMarkerLabel`, `MapMarkerPopup` (opens on click) and `MapMarkerTooltip`
+ * (shows on hover).
  */
 export function MapMarker({
-  longitude,
-  latitude,
+  longitude: longitudeProp,
+  latitude: latitudeProp,
+  x,
+  y,
   children,
   onClick,
   onMouseEnter,
@@ -60,9 +116,25 @@ export function MapMarker({
   onDrag,
   onDragEnd,
   draggable = false,
+  dragLabel,
+  showAt = true,
+  label,
   ...markerOptions
 }: MapMarkerProps) {
-  const { map } = useMap();
+  const { map, plan } = useMap();
+  const { t } = useLocale();
+  const visible = resolveMapResponsive(showAt, useMapBreakpoint());
+  const [marker, setMarker] = useState<MapLibreGL.Marker | null>(null);
+
+  // One position prop, two coordinate systems, two scalars out — so every sync
+  // effect below keeps primitive dependencies.
+  const [longitude, latitude] = resolveMapPosition(
+    { longitude: longitudeProp, latitude: latitudeProp, x, y },
+    plan,
+    "MapMarker",
+  );
+  const planRef = useRef(plan);
+  planRef.current = plan;
 
   const callbacksRef = useRef({
     onClick,
@@ -81,12 +153,39 @@ export function MapMarker({
     onDragEnd,
   };
 
-  const marker = useMemo(() => {
+  const { anchor, className, offset, rotation, rotationAlignment, pitchAlignment } = markerOptions;
+
+  // `longitude`/`latitude`/`draggable` at construction time only — the sync
+  // effect below corrects them on the very next commit, and are read from a
+  // ref here so they don't force a rebuild on every position change (see the
+  // `anchor`/`className` note below for what SHOULD force one).
+  const initialRef = useRef({ longitude, latitude, draggable });
+  initialRef.current = { longitude, latitude, draggable };
+
+  // Builds (and tears down) the actual MapLibre `Marker` instance. This is a
+  // real `useEffect`, never `useMemo`: `useMemo`'s initializer runs during
+  // RENDER — including on the server, where `document` doesn't exist — and
+  // React offers no guarantee it runs only once (it may discard and recompute
+  // a memoized value), which would silently leak marker instances/listeners.
+  //
+  // `anchor` and `className` have no MapLibre setter (`Marker` bakes both into
+  // its constructor), so they are the only options that must REBUILD the
+  // instance; every other option (position, draggable, offset, rotation,
+  // alignment) has a live setter and is kept in sync by the effect further
+  // below without ever recreating the marker.
+  useEffect(() => {
     const markerInstance = new MapLibreGL.Marker({
-      ...markerOptions,
+      anchor,
+      className,
       element: document.createElement("div"),
-      draggable,
-    }).setLngLat([longitude, latitude]);
+      draggable: initialRef.current.draggable,
+    }).setLngLat([initialRef.current.longitude, initialRef.current.latitude]);
+
+    // c-10: MapLibre gives a marker a tab stop of its own (a popup, a
+    // keyboard drag), and a raw element shows the BROWSER's focus ring, which
+    // does not follow the theme. The house indicator is a class, so the
+    // element wears the same `focus-ring` every other control does.
+    markerInstance.getElement()?.classList.add("focus-ring");
 
     const handleClick = (e: MouseEvent) => callbacksRef.current.onClick?.(e);
     const handleMouseEnter = (e: MouseEvent) => callbacksRef.current.onMouseEnter?.(e);
@@ -98,39 +197,50 @@ export function MapMarker({
 
     const handleDragStart = () => {
       const lngLat = markerInstance.getLngLat();
-      callbacksRef.current.onDragStart?.({ lng: lngLat.lng, lat: lngLat.lat });
+      callbacksRef.current.onDragStart?.(
+        { lng: lngLat.lng, lat: lngLat.lat },
+        toPlanPoint(planRef.current, lngLat),
+      );
     };
     const handleDrag = () => {
       const lngLat = markerInstance.getLngLat();
-      callbacksRef.current.onDrag?.({ lng: lngLat.lng, lat: lngLat.lat });
+      callbacksRef.current.onDrag?.(
+        { lng: lngLat.lng, lat: lngLat.lat },
+        toPlanPoint(planRef.current, lngLat),
+      );
     };
     const handleDragEnd = () => {
       const lngLat = markerInstance.getLngLat();
-      callbacksRef.current.onDragEnd?.({ lng: lngLat.lng, lat: lngLat.lat });
+      callbacksRef.current.onDragEnd?.(
+        { lng: lngLat.lng, lat: lngLat.lat },
+        toPlanPoint(planRef.current, lngLat),
+      );
     };
 
     markerInstance.on("dragstart", handleDragStart);
     markerInstance.on("drag", handleDrag);
     markerInstance.on("dragend", handleDragEnd);
 
-    return markerInstance;
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- instance created once; position/options are synced by the effect below
-  }, []);
+    setMarker(markerInstance);
+  }, [anchor, className]);
 
+  // Attaches/detaches the CURRENT marker instance to the map — its own effect
+  // so both a `map` change and an `anchor`/`className`-driven rebuild above
+  // are handled the same way, without a double `remove()`.
+  // A marker hidden at this tier (`showAt`) is simply not on the map.
   useEffect(() => {
-    if (!map) return;
+    if (!map || !marker || !visible) return;
 
     marker.addTo(map);
 
     return () => {
       marker.remove();
     };
-    // eslint-disable-next-line react-hooks/exhaustive-deps -- `marker` is stable (created once above)
-  }, [map]);
-
-  const { offset, rotation, rotationAlignment, pitchAlignment } = markerOptions;
+  }, [map, marker, visible]);
 
   useEffect(() => {
+    if (!marker) return;
+
     const current = marker.getLngLat();
     if (current.lng !== longitude || current.lat !== latitude) {
       marker.setLngLat([longitude, latitude]);
@@ -160,7 +270,238 @@ export function MapMarker({
     }
   }, [marker, longitude, latitude, draggable, offset, rotation, rotationAlignment, pitchAlignment]);
 
-  return <MarkerContext.Provider value={{ marker, map }}>{children}</MarkerContext.Provider>;
+  // c-4 (WCAG 2.1.1): `marker.setDraggable(true)` buys a MOUSE affordance and
+  // nothing else — MapLibre gives a marker element a tab stop and a key
+  // handler only from inside `setPopup`, so a popup-less draggable marker is
+  // not focusable and answers no key. The drag gets its keyboard equivalent
+  // here: a real tab stop, a name that says what moves, and arrow keys that
+  // step the marker in PIXELS (Shift = a coarser step) through the same
+  // project/unproject round trip the pointer drag uses, firing the identical
+  // dragstart/drag/dragend payloads.
+  useEffect(() => {
+    const element = marker?.getElement();
+    if (!(draggable && marker && map && element)) return;
+
+    const hadTabIndex = element.getAttribute("tabindex");
+    const hadRole = element.getAttribute("role");
+    const hadLabel = element.getAttribute("aria-label");
+    if (hadTabIndex === null) element.setAttribute("tabindex", "0");
+    if (hadRole === null) element.setAttribute("role", "button");
+    // MapLibre's own name is the generic "Map marker"; it says neither what
+    // this one moves nor that it can be moved at all. A draggable marker is
+    // named for its drag, and the original name goes back on cleanup.
+    element.setAttribute("aria-label", dragLabel ?? t("maps.marker.drag"));
+
+    let dragging = false;
+    const position = () => {
+      const lngLat = marker.getLngLat();
+      return { lng: lngLat.lng, lat: lngLat.lat };
+    };
+    // The keyboard path reports the plan point exactly as the pointer path
+    // does, so a plan consumer cannot tell the two apart.
+    const planPoint = () => toPlanPoint(planRef.current, marker.getLngLat());
+    const settle = () => {
+      if (!dragging) return;
+      dragging = false;
+      callbacksRef.current.onDragEnd?.(position(), planPoint());
+    };
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      const step = event.shiftKey ? KEYBOARD_DRAG_STEP_COARSE_PX : KEYBOARD_DRAG_STEP_PX;
+      const delta = KEYBOARD_DRAG_DELTAS[event.key];
+      if (!delta) return;
+      event.preventDefault();
+      // MapLibre appends the marker element straight into
+      // `map.getCanvasContainer()` — the SAME element its own
+      // `HandlerManager` listens on for `keydown` (bubble phase, no
+      // `defaultPrevented` check). Without this, every arrow key we handle
+      // here also reaches MapLibre's built-in keyboard pan handler, which
+      // fires an `easeTo` that moves the CAMERA by 100px the opposite way
+      // (its `offset` is negated) and — since that `easeTo` isn't marked
+      // `essential` — collapses to an instant jump under reduced motion but
+      // animates over 300ms otherwise, so repeated presses compose
+      // differently per motion setting. Stopping propagation keeps the key
+      // entirely inside this handler: only `marker.setLngLat` moves, the
+      // camera never does.
+      event.stopPropagation();
+      if (!dragging) {
+        dragging = true;
+        callbacksRef.current.onDragStart?.(position(), planPoint());
+      }
+      const point = map.project(marker.getLngLat());
+      const next = map.unproject([point.x + delta[0] * step, point.y + delta[1] * step]);
+      marker.setLngLat(next);
+      callbacksRef.current.onDrag?.(position(), planPoint());
+    };
+    const handleKeyUp = (event: KeyboardEvent) => {
+      if (KEYBOARD_DRAG_DELTAS[event.key]) settle();
+    };
+
+    element.addEventListener("keydown", handleKeyDown);
+    element.addEventListener("keyup", handleKeyUp);
+    element.addEventListener("blur", settle);
+
+    return () => {
+      element.removeEventListener("keydown", handleKeyDown);
+      element.removeEventListener("keyup", handleKeyUp);
+      element.removeEventListener("blur", settle);
+      if (hadTabIndex === null) element.removeAttribute("tabindex");
+      if (hadRole === null) element.removeAttribute("role");
+      if (hadLabel === null) element.removeAttribute("aria-label");
+      else element.setAttribute("aria-label", hadLabel);
+    };
+  }, [draggable, dragLabel, map, marker, t]);
+
+  // No marker yet (first client tick after mount, or the moment an
+  // `anchor`/`className` rebuild is in flight) — render nothing rather than
+  // a sub-component (`MapMarkerContent` et al.) reaching into a null marker,
+  // and nothing at all on the server.
+  if (!marker) {
+    return null;
+  }
+
+  return (
+    <MarkerContext.Provider value={{ marker, map }}>
+      {children}
+      {label && <MarkerOwnLabel label={label} />}
+    </MarkerContext.Provider>
+  );
+}
+
+/** One arrow-key press of a keyboard drag, in screen px (c-4). */
+const KEYBOARD_DRAG_STEP_PX = 8;
+/** The same press with Shift held — a coarser step across the map. */
+const KEYBOARD_DRAG_STEP_COARSE_PX = 40;
+/** Arrow key → screen-space direction. `y` grows downward, as `map.project` does. */
+const KEYBOARD_DRAG_DELTAS: Record<string, [number, number] | undefined> = {
+  ArrowLeft: [-1, 0],
+  ArrowRight: [1, 0],
+  ArrowUp: [0, -1],
+  ArrowDown: [0, 1],
+};
+
+const LABEL_GAP = 10;
+const CALLOUT_DISTANCE = 28;
+/** How close to the map's edge a clamped label may sit, in px. */
+const LABEL_EDGE_PAD = 4;
+
+/**
+ * Keep a marker's label inside the map box (c-7 / c-8).
+ *
+ * A label is a pure offset from its marker, so at the edge of a static map it
+ * was painted half outside the box and clipped — "bottom-righ", "…urg Gate" —
+ * with no way to pan it back into view. This is the pass `MapAnnotation`
+ * already makes: measure the painted box, clamp it into the map's rectangle
+ * with `clampShift`, and write the correction to the CSS `translate` property,
+ * which composes with the label's own `transform` instead of replacing it.
+ *
+ * A label whose own point has left the box is hidden rather than pinned to the
+ * edge: a name parked at the border beside no marker claims a place the reader
+ * cannot see. Skipped while the map box measures 0 (jsdom, first paint).
+ */
+function useLabelInsideMap(
+  element: HTMLElement | null,
+  map: MapLibreGL.Map | null,
+  marker: MapLibreGL.Marker,
+  onShift?: (sx: number, sy: number) => void,
+) {
+  const onShiftRef = useRef(onShift);
+  onShiftRef.current = onShift;
+
+  useLayoutEffect(() => {
+    if (!element || !map) return undefined;
+    const container = map.getContainer();
+
+    const update = () => {
+      const frame = container.getBoundingClientRect();
+      if (frame.width === 0 || frame.height === 0) return;
+
+      const point = map.project(marker.getLngLat());
+      const inside =
+        point.x >= 0 && point.y >= 0 && point.x <= frame.width && point.y <= frame.height;
+      element.style.visibility = inside ? "" : "hidden";
+      if (!inside) return;
+
+      // Measure the label where it would sit unshifted, then re-apply.
+      element.style.translate = "";
+      const box = element.getBoundingClientRect();
+      const { sx, sy } = clampShift(
+        box.left - frame.left,
+        box.top - frame.top,
+        box.width,
+        box.height,
+        frame.width,
+        frame.height,
+        LABEL_EDGE_PAD,
+      );
+      element.style.translate = sx === 0 && sy === 0 ? "" : `${sx}px ${sy}px`;
+      onShiftRef.current?.(sx, sy);
+    };
+
+    update();
+    map.on("move", update);
+    map.on("resize", update);
+    const observer =
+      typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => update());
+    observer?.observe(element);
+    return () => {
+      map.off("move", update);
+      map.off("resize", update);
+      observer?.disconnect();
+    };
+  }, [element, map, marker]);
+}
+
+/** The `label` prop, portaled into the marker element and centred on the point. */
+function MarkerOwnLabel({ label }: { label: MapMarkerLabelSpec }) {
+  const { marker, map } = useMarkerContext();
+  const { text, position = "top", box = false, callout = false } = label;
+  const distance = callout ? CALLOUT_DISTANCE : LABEL_GAP;
+  const { dx, dy } = mapAnchorGeometry(position, distance);
+  const [labelEl, setLabelEl] = useState<HTMLDivElement | null>(null);
+  const lineRef = useRef<SVGLineElement | null>(null);
+
+  // A clamped label pulls its callout line's end along with it, so the line
+  // still meets the box it points at.
+  useLabelInsideMap(labelEl, map, marker, (sx, sy) => {
+    const line = lineRef.current;
+    if (!line) return;
+    line.setAttribute("x2", String(dx + sx));
+    line.setAttribute("y2", String(dy + sy));
+  });
+
+  return createPortal(
+    <>
+      {callout && (
+        <svg
+          aria-hidden="true"
+          data-slot="map-marker-callout"
+          className="pointer-events-none absolute overflow-visible text-foreground"
+          // The marker element is centred on the point; draw from its centre.
+          style={{ left: "50%", top: "50%" }}
+          width={1}
+          height={1}
+        >
+          <line ref={lineRef} x1={0} y1={0} x2={dx} y2={dy} stroke="currentColor" strokeWidth={1} />
+        </svg>
+      )}
+      <div
+        ref={setLabelEl}
+        data-slot="map-marker-label"
+        data-position={position}
+        className={cn(
+          "pointer-events-none absolute whitespace-nowrap text-meta font-medium text-foreground",
+          box && "rounded-sm bg-background/90 px-1 py-px",
+        )}
+        // Geographic placement: physical offsets from the point in every
+        // writing direction (east stays east), like MapLibre's own anchors.
+        style={{ left: "50%", top: "50%", transform: mapAnchorTransform(position, distance) }}
+      >
+        {text}
+      </div>
+    </>,
+    marker.getElement(),
+  );
 }
 
 export interface MapMarkerContentProps {
@@ -189,11 +530,12 @@ function DefaultMarkerIcon() {
 }
 
 function PopupCloseButton({ onClick }: { onClick: () => void }) {
+  const { t } = useLocale();
   return (
     <button
       type="button"
       onClick={onClick}
-      aria-label="Close popup"
+      aria-label={t("maps.popup.close")}
       className="absolute top-1 right-1 z-10 inline-flex size-5 items-center justify-center rounded-sm text-foreground transition-colors duration-fast hover:bg-muted focus-ring-inset"
     >
       <X className="size-3.5" aria-hidden="true" />
@@ -297,17 +639,36 @@ export function MapMarkerTooltip({ children, className, ...popupOptions }: MapMa
 
     tooltip.setDOMContent(container);
 
-    const handleMouseEnter = () => {
+    const show = () => {
       tooltip.setLngLat(marker.getLngLat()).addTo(map);
     };
-    const handleMouseLeave = () => tooltip.remove();
+    const hide = () => tooltip.remove();
+    // WCAG 1.4.13: a tooltip that only answers a pointer is unreachable, and
+    // one that cannot be dismissed without moving the pointer traps the view.
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === "Escape") hide();
+    };
+
+    const element = marker.getElement();
+    // MapLibre only makes a marker focusable inside `setPopup`, so a
+    // tooltip-only marker has to ask for the tab stop itself. The original
+    // value is put back on cleanup, so a marker that had one keeps it.
+    const hadTabIndex = element?.getAttribute("tabindex") ?? null;
+    if (element && hadTabIndex === null) element.setAttribute("tabindex", "0");
 
-    marker.getElement()?.addEventListener("mouseenter", handleMouseEnter);
-    marker.getElement()?.addEventListener("mouseleave", handleMouseLeave);
+    element?.addEventListener("mouseenter", show);
+    element?.addEventListener("mouseleave", hide);
+    element?.addEventListener("focus", show);
+    element?.addEventListener("blur", hide);
+    element?.addEventListener("keydown", handleKeyDown);
 
     return () => {
-      marker.getElement()?.removeEventListener("mouseenter", handleMouseEnter);
-      marker.getElement()?.removeEventListener("mouseleave", handleMouseLeave);
+      element?.removeEventListener("mouseenter", show);
+      element?.removeEventListener("mouseleave", hide);
+      element?.removeEventListener("focus", show);
+      element?.removeEventListener("blur", hide);
+      element?.removeEventListener("keydown", handleKeyDown);
+      if (element && hadTabIndex === null) element.removeAttribute("tabindex");
       tooltip.remove();
     };
     // eslint-disable-next-line react-hooks/exhaustive-deps -- tooltip/marker/container are stable
@@ -351,14 +712,23 @@ export interface MapMarkerLabelProps {
  * sibling composition rendering the label against the map container instead).
  */
 export function MapMarkerLabel({ children, className, position = "top" }: MapMarkerLabelProps) {
-  const { marker } = useMarkerContext();
+  const { marker, map } = useMarkerContext();
+  const [labelEl, setLabelEl] = useState<HTMLDivElement | null>(null);
   const positionClasses = {
     top: "bottom-full mb-1",
     bottom: "top-full mt-1",
   };
 
+  // Same edge clamp as the `label` prop's own label (c-7 / c-8): a composed
+  // label is a plain offset from the marker too, so at the map's edge it was
+  // painted outside the box and clipped.
+  useLabelInsideMap(labelEl, map, marker);
+
   return createPortal(
     <div
+      ref={setLabelEl}
+      data-slot="map-marker-label"
+      data-position={position}
       className={cn(
         "absolute left-1/2 -translate-x-1/2 whitespace-nowrap",
         "text-meta font-medium text-foreground",

package/src/map-north-arrow/index.ts

@@ -0,0 +1 @@
+export { MapNorthArrow, type MapNorthArrowProps } from "./map-north-arrow";

package/src/map-north-arrow/map-north-arrow.stories.tsx

@@ -0,0 +1,65 @@
+import type { Meta, StoryObj } from "@storybook/react-vite";
+import { expect, waitFor } from "storybook/test";
+
+import { MapCanvas } from "../map-canvas";
+import { MapNorthArrow } from "./map-north-arrow";
+
+const meta = {
+  title: "Maps/MapNorthArrow",
+  component: MapNorthArrow,
+  tags: ["autodocs"],
+  parameters: { layout: "fullscreen" },
+} satisfies Meta<typeof MapNorthArrow>;
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * A rotated map (bearing 30°) shows the arrow, turned to point at true north.
+ * On a north-up map the arrow stays hidden — it would only state the default.
+ */
+export const Default: Story = {
+  render: (args) => (
+    <div className="w-full p-4">
+      <MapCanvas interactive={false} center={[-79.38, 43.65]} zoom={9} bearing={30}>
+        <MapNorthArrow {...args} />
+      </MapCanvas>
+    </div>
+  ),
+  play: async ({ canvasElement }) => {
+    if (!canvasElement.querySelector(".maplibregl-canvas")) return;
+    await waitFor(() => {
+      const arrow = canvasElement.querySelector<HTMLElement>('[data-slot="map-north-arrow"]');
+      expect(arrow).not.toBeNull();
+      expect(arrow!.hidden).toBe(false);
+    });
+  },
+};
+
+/** North-up: nothing to show. */
+export const NorthUp: Story = {
+  render: () => (
+    <div className="w-full p-4">
+      <MapCanvas interactive={false} center={[-79.38, 43.65]} zoom={9}>
+        <MapNorthArrow />
+      </MapCanvas>
+    </div>
+  ),
+};
+
+/** In another corner, with a translated name. */
+export const Positioned: Story = {
+  args: { position: "bottom-right", label: "Norden" },
+  render: Default.render,
+};
+
+/** The remaining corners. */
+export const OtherCorners: Story = {
+  render: () => (
+    <div className="w-full p-4">
+      <MapCanvas interactive={false} center={[-79.38, 43.65]} zoom={9} bearing={-45}>
+        <MapNorthArrow position="top-right" />
+        <MapNorthArrow position="bottom-left" />
+      </MapCanvas>
+    </div>
+  ),
+};

package/src/map-north-arrow/map-north-arrow.test.tsx

@@ -0,0 +1,39 @@
+import { act, cleanup, render, screen, 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 { MapNorthArrow } from "./map-north-arrow";
+
+afterEach(() => {
+  cleanup();
+  resetMaplibreMock();
+});
+
+describe("MapNorthArrow", () => {
+  it("stays away on a north-up map and appears once the map rotates", async () => {
+    render(
+      <MapCanvas>
+        <MapNorthArrow />
+      </MapCanvas>,
+    );
+    const arrow = await waitFor(() => {
+      const el = document.querySelector('[data-slot="map-north-arrow"]');
+      expect(el).not.toBeNull();
+      return el!;
+    });
+    expect(arrow).toHaveAttribute("hidden");
+    act(() => {
+      MockMap.instances[0]!.bearing = 30;
+      MockMap.instances[0]!.emit("rotate");
+    });
+    expect(arrow).not.toHaveAttribute("hidden");
+    expect(screen.getByRole("img", { name: "North" })).toBeVisible();
+    expect(arrow.querySelector("svg")!.style.transform).toBe("rotate(-30deg)");
+  });
+});