@mapmap/maps 0.4.0 → 0.5.1

package/README.md

@@ -372,6 +372,102 @@ puck.setLocation({ lat: 51.5074, lon: -0.1278 }, 45); // heading in degrees
   pitch/zoom as its option defaults when built from a `MapMapMap`; explicit
   options still win (option > design > built-in). Themes saved without the
   block load unchanged and stay `"version": 1`.
+- `extra.nav.alerts` (optional since v1) holds the safety-camera alert
+  design: chip tokens (`background`, `textColor`, `outlineColor`,
+  `cornerRadius` 0-24, `outlineWidth` 0-4), the always-present escalated
+  pair (`escalatedBackground`, `escalatedTextColor`), `iconSet`
+  (`european` / `us` / `minimal` / `brand`) with optional per-kind
+  `iconUrlOverrides`, `alertSound` and `escalatedSound` from the built-in
+  earcon library (`cameraCalm`, `cameraUrgent`, `overspeedSoft`,
+  `zoneEnter`, `zoneClear`) with optional `alertSoundUrl` /
+  `escalatedSoundUrl` overrides, `mapIconSize` (0.75-1.5) and
+  `mapMinZoom` (9-14),
+  `corridorColor` / `corridorOpacity` for the average-speed corridor,
+  `leadDistance` (`short` / `standard` / `long` = 150 m / 250 m / 400 m
+  floors), `chipPosition` (`aboveSpeed` / `topLeading` / `topTrailing`)
+  and a `kinds` entry per camera kind (`fixed`, `average`, `red_light`,
+  `mobile_site`, `unknown`) carrying `showOnMap` (browse-mode map
+  display), `showOnMapWhileNavigating` (map display during guidance,
+  default true), `alertWhileDriving`, `showInRoutePreview`, `alertMode`
+  (`always` / `whenSpeeding` / `never`) and `audioMode` (`off` /
+  `earcon` / `earcon_and_speech`).
+
+  ```ts
+  import { CameraAlertChip, alertPresentation, navCameraKind } from "@mapmap/maps";
+
+  const chip = new CameraAlertChip(document.body, map.navDesign?.alerts);
+  // Visual is unconditional and calm; audio is the escalation channel.
+  chip.update({ kind: "fixed", limitKph: 30, distanceM: 240 }, { speeding: false });
+
+  // Average-speed corridors tint the route line itself.
+  routes.setAlertCorridors([corridorGeometry]);
+  ```
+
+  `alertPresentation(design, alert, { speeding })` is the pure rule behind
+  the chip: it returns whether to show it, whether to escalate, whether
+  audio fires and the lead-distance floor in metres. `alertChipContent`
+  returns just the title, subtitle and icon URL, which is what CarPlay's
+  `CPNavigationAlert` and Android Auto's `Alert` accept - colours, radius
+  and position do not survive a head-unit template, so styling degrades to
+  the platform look there rather than being assumed to render.
+  `alertContrastIssues(design)` runs a WCAG contrast check over both chip
+  colour pairs (floor 4.5:1); Studio surfaces the same warnings as you
+  pick colours.
+
+  **Sound.** `alertPresentation(...).soundUrl` is the earcon to play for
+  the state it just resolved - the calm sound, or its escalated variant
+  when the driver is over the limit - so a host never picks the file
+  itself. `alertSoundUrl(design, escalated)` is the same rule standalone.
+  The SDK bundles no audio: the built-ins resolve to
+  `https://mapmap.ai/earcons/*.mp3` (public and unmetered), and
+  `navAlertSoundUrl(sound, baseUrl)` re-points them at your own host.
+
+  ```ts
+  const p = alertPresentation(design, alert, { speeding });
+  if (p.audible) {
+    const audio = new Audio(p.soundUrl);
+    audio.volume = 1; // the app owns the in-car level, not the theme
+    void audio.play()?.catch?.(() => {});
+  }
+  ```
+
+  There are exactly two sounds, and that is deliberate. Which camera it is
+  travels in the icon and in the spoken line; how urgent it is travels in
+  the timbre. Per-kind chimes would ask a driver to learn five sounds at
+  motorway speed, which no shipping product does.
+
+  **Camera POIs on the map.** Cameras are not in the vector tiles - they
+  come from the gateway's `POST /v1/cameras/along`, behind the same
+  server-side jurisdiction policy - so a style draws them over a GeoJSON
+  source you add. `cameraSymbolLayer(design, sourceId, mode, variant)`
+  builds that layer: sprite icons per kind, the design's `mapIconSize` and
+  `mapMinZoom`, and a filter holding only the kinds that mode shows.
+
+  ```ts
+  map.addSource("cameras", { type: "geojson", data: camerasGeoJson });
+  map.addLayer(cameraSymbolLayer(design, "cameras", "navigating", "light"));
+  ```
+
+  The icons ship in the published sprite sheet
+  (`https://api.mapmap.ai/sprite/sprite`), generated from the same glyphs
+  the chip draws, so the pin and the chip are never two different cameras.
+  Image ids come from `cameraSpriteName(kind, variant)` -
+  `camera-fixed-dark`, `camera-redlight-light` and so on, `-dark` for
+  light basemaps and `-light` for dark ones. Your style must carry a
+  `sprite` URL for them to render; the skeleton ships none by default.
+
+  `cameraShownOnMap(design, kind, mode)` is the underlying rule.
+  `"browse"` reads `showOnMap` and `"navigating"` reads
+  `showOnMapWhileNavigating`, because showing a camera while planning and
+  showing it while driving are separate decisions - the market warns with
+  or without a planned route, so map display is not gated behind
+  guidance.
+
+  **Jurisdiction policy is server side and is not styleable.** Whether a
+  camera may be returned at all is decided per country by the gateway
+  before the response leaves it. This block styles what policy already
+  permits; it cannot widen it.
+
 - The nav block travels with the **theme document**, never the compiled
   style: `extra` round-trips through `POST /styles` and
   `GET /styles/{id}/theme` (bounded at 256 KB serialised), but a compiled
@@ -501,37 +597,51 @@ const route = await routes.route(from, to, {
 
 const steps = extractGuidance(route);
 const banner = new GuidanceBanner(document.body, map.navDesign?.banner);
-banner.update(steps[0].banners[0] ?? null);
+// Pass the step as the second argument so ferry legs get the ferry glyph
+// and u-turns point the right way in left-hand-traffic regions.
+banner.update(steps[0].banners[0] ?? null, steps[0]);
 // As the driver advances, fire each voice prompt once when its
 // distanceAlongGeometry trigger is crossed:
 speak(steps[0].voice[0]);
 ```
 
-Voice prompts arrive plain and as SSML; banners carry the maneuver glyph
-and, where OSM has `turn:lanes` data, a lane diagram (sprite icons
-`lane-left`, `lane-straight`, … ship with the map assets).
+Voice prompts arrive plain and as SSML. The banner renders the manoeuvre
+glyph from the platform's direction-icon set (roundabouts, forks, ramps,
+ferries — see below) sized to the design's font, and, where OSM has
+`turn:lanes` data, a lane diagram (sprite icons `lane-left`,
+`lane-straight`, … ship with the map assets). The glyph's secondary shapes
+retheme via the `--mm-icon-secondary` CSS custom property.
 
 ### Direction icons (`@mapmap/maps/direction-icons`)
 
-A separate entry point (so the core bundle is unaffected) with the platform's
-90-icon manoeuvre set as inline SVG, plus the OSRM maneuver mapping:
+The platform's 90-icon manoeuvre set as inline SVG, plus the OSRM maneuver
+mapping. Available from the main entry and as a separate
+`@mapmap/maps/direction-icons` entry point; apps that use neither
+`GuidanceBanner` nor the icons tree-shake the set away entirely:
 
 ```ts
 import {
   directionIcons,          // { turn_left: "<svg…>", roundabout_right: …, ferry: … }
+  iconNameForStep,         // (step) => DirectionIconName — preferred
   iconNameForManeuver,     // (type?, modifier?, drivingSide?) => DirectionIconName
   directionIconSvg,        // shorthand: the SVG for a maneuver
 } from "@mapmap/maps/direction-icons";
 
-el.innerHTML = directionIconSvg(step.maneuver.type, step.maneuver.modifier);
+el.innerHTML = directionIcons[iconNameForStep(step)];
 ```
 
 Icons are 20×20 `viewBox` SVGs. The arrow inherits `currentColor`; secondary
 road furniture (other lanes, the rest of a roundabout ring, ferry water) is
 filled with `var(--mm-icon-secondary, #C9CDD2)` — set that CSS custom
 property to retheme it. Unknown maneuvers degrade to the plain turn family,
-never a missing icon; pass `drivingSide: "left"` for left-hand-traffic
-u-turns.
+never a missing icon.
+
+Prefer `iconNameForStep(step)`: it reads everything off the OSRM step
+itself — ferry legs from `step.mode`, and the u-turn direction from
+`step.driving_side` (the MapMap gateway emits it on u-turn steps), so
+left-hand-traffic markets render `uturn_right` with no configuration.
+The lower-level `iconNameForManeuver` remains for callers without a step
+object; it defaults to right-hand traffic.
 
 ## Navigation camera