@mapmap/maps 0.5.2 → 0.7.0

package/README.md

@@ -90,17 +90,86 @@ new MapMapMap({
 ```ts
 const routes = new RouteLayer(map /* MapMapMap or maplibregl.Map */, {
   baseUrl?, apiKey?, id?, design?, // design: extra.nav route block
+  endpoints?,                      // start/end/waypoint markers, off by default
 });
 
 await routes.route(from, to, { profile, truck });      // two-point
 await routes.routePath([a, b, c], { profile, truck }); // multi-point
-routes.current;  // last ParsedRoute
-routes.clear();  // remove the drawn line
+routes.draw(parsedRoute);          // a route parsed elsewhere
+routes.current;   // last ParsedRoute
+routes.ids;       // the source/layer ids this layer owns
+routes.clear();   // remove the drawn line and everything hung off it
+routes.destroy(); // clear() + detach the style.load listener
+
+// Draw geometry you already have, with no ParsedRoute to hand
+routes.drawGeometry([[lng, lat], ...]);
+
+// Intermediate stops, for the numbered waypoint markers
+routes.setWaypoints([[lng, lat]]);
+routes.currentWaypoints;   // read them back
+
+// Alternatives: one selected, the rest dimmer beneath and clickable
+routes.drawAlternatives(parsedRoutes, selectedIndex);
+routes.onSelectAlternative((i) => routes.drawAlternatives(parsedRoutes, i));
+routes.alternativeRoutes;  // what is currently drawn as an alternative
+
+// Ferry legs as dashes over the selected line, so water does not read
+// as driving. Supplied explicitly: line-dasharray cannot be data-driven,
+// and only you know which parts of your route are ferries.
+routes.setFerrySegments([[[lng, lat], ...]]);
+routes.clearFerrySegments();
+
+// Runtime paint, over the design. Survives style reloads; `{}` clears.
+// A provisional or straight-line-approximated route, for example:
+routes.setLineStyle({ color: "#9096a2", dash: [1.6, 1.4], casingOpacity: 0 });
 ```
 
+`ids` names every MapLibre id the layer owns, so you can restyle or reorder
+them: `source`, `casing`, `line`, `maneuverSource`, `maneuver`,
+`corridorSource`, `corridor`, `endpointsSource` and `endpoints`. All are
+derived from the `id` option (default `mapmap-route`).
+
+#### Start, end and waypoint markers
+
+`endpoints: true` draws branded markers on the route: a green `dot` at the
+first coordinate, a signal-blue `pin` at the last, and smaller pins
+numbered 1..n at each intermediate stop. Override any of them, or pass
+`false` to drop one:
+
+```ts
+new RouteLayer(map, {
+  endpoints: {
+    start: { icon: "home", colour: "#3ecf8e", size: "m", label: "Depot" },
+    end: { text: "B" },      // 1–3 characters beat the glyph
+    waypoint: false,         // no intermediate markers
+    numberWaypoints: true,   // default
+  },
+});
+```
+
+The stops come from `routePath`'s via points; when you hand a route parsed
+elsewhere to `draw()` or `drawGeometry()`, set them with
+`routes.setWaypoints([[lng, lat], …])` and read them back from
+`routes.currentWaypoints`. An empty array clears them.
+
+The markers are a symbol layer over their own source (both ids
+`<id>-endpoints`, on `routes.ids` as `endpoints` and `endpointsSource`),
+not DOM markers, so they appear in canvas exports and match the native
+SDKs. A pin anchors at its tip, a `dot` at its centre; `label` draws below
+the marker with a white halo and is optional to the collision detector.
+They survive `setStyle`, and `clear()`/`destroy()` removes the layer, the
+source and the images this layer registered. Omit the option and the layer
+behaves exactly as before.
+
 Coordinates accept `[lng, lat]`, `{ lng, lat }` or `{ lon, lat }`. A route
 resolves to `{ distanceM, durationS, geometry (GeoJSON LineString), raw }`.
 
+The `design` block takes `color`, `width`, `opacity` and `casingColor`, plus
+three optional fields: `casingWidth` (defaults to `width + 4`),
+`casingOpacity` (defaults to `opacity`) and `dash` (omitted or `null` draws
+solid). Set the first two when your casing is not exactly four wider than
+your line, or when it is translucent under a solid line.
+
 `truck` params map onto the gateway's OSRM truck vendor extensions:
 `heightM`, `widthM`, `lengthM`, `weightT`, `hazmat`, and `tunnelCode` (ADR
 8.6.4, e.g. `"C"` or `"B/D"` - the slash is URL-encoded for you). They only
@@ -150,7 +219,7 @@ stores.select("man-01");                         // list→map sync: popup + cam
 stores.deselect();                               // close the popup
 stores.nearest({ lat: 51.5, lon: -0.13 }, 3);    // haversine, adds distanceM
 await stores.nearestByDriveTime({ lat: 51.5, lon: -0.13 }, { n: 3, costing: "truck" });
-stores.ids;       // { source, points, clusters, clusterCounts } - see below
+stores.ids;       // { source, points, clusters, clusterCounts, labels, pointsFallback }
 stores.clear();   // remove pins;  stores.destroy() also detaches listeners
 ```
 
@@ -213,17 +282,116 @@ the `Place`, or `undefined` for an unknown id (nothing happens). It does
 #### Escape-hatch styling: `ids`
 
 The generated MapLibre ids are public API via `stores.ids` →
-`{ source, points, clusters, clusterCounts }`, so raw MapLibre calls are
-supported when the options don't reach far enough:
+`{ source, points, clusters, clusterCounts, labels, pointsFallback }`, so raw
+MapLibre calls are supported when the options don't reach far enough:
 
 ```ts
 map.setPaintProperty(stores.ids.points, "circle-radius", 9);
 map.queryRenderedFeatures({ layers: [stores.ids.points] });
 ```
 
-`clusters`/`clusterCounts` are only installed with `cluster: true` (the
-default); `points` is a circle layer by default, or a symbol layer once a
-custom `icon` has loaded.
+Not every id is installed on the map at all times - the object always
+carries all six, but a layer only exists when its feature is switched on:
+
+- `clusters`/`clusterCounts` - only with `cluster: true` (the default).
+- `labels` - only with a `label` option (see below).
+- `pointsFallback` - only when `icon` is a **record** of per-place images:
+  it is the circle layer drawn under places whose icon hasn't loaded (or
+  doesn't exist).
+- `points` is a circle layer by default, or a symbol layer once a single
+  custom `icon` has loaded.
+
+#### Per-place labels
+
+`label: true` writes each place's `name` beside its point; an options
+object tunes it:
+
+```ts
+new PlacesLayer(map, {
+  places,
+  label: { property: "name", size: 12, colour: "#333333", haloColour: "#ffffff" },
+});
+```
+
+Both spellings are accepted for the two colour keys - `colour`/`haloColour`
+and `color`/`haloColor` (British wins if both are given) - so a
+dynamically-built options object can't lose its label colours to a spelling
+mismatch with the sibling `color`/`clusterColor` options. Labels only ever
+draw on unclustered points, and hide before colliding (`text-optional`).
+
+> Labels need the **`MapMap Sans Regular`** fontstack from the style's
+> `glyphs` endpoint. Every MapMap style ships it; a theme pointed at a
+> custom glyphs host that doesn't serve it drops the labels **silently**
+> (MapLibre logs a glyph 404 and renders the points alone). The same
+> applies to marker labels below.
+
+### `class MarkersLayer` - markers designed in Studio
+
+Custom markers and labels that travel **with the theme**, under
+`extra.markers` (schema v1): up to 200 coloured glyph pins, plain dots or
+small custom images, each with an optional label. They are placed in
+Studio's Markers tab, so a designer can ship "here are our depots" with the
+style itself - no places data, no code change:
+
+```ts
+import { MarkersLayer, markersFromThemeUrl } from "@mapmap/maps";
+
+const markers = await markersFromThemeUrl(
+  "https://api.mapmap.ai/styles/midnight-fleet-a1b2c3/theme",
+);
+if (markers) new MarkersLayer(map /* MapMapMap or maplibregl.Map */, markers);
+```
+
+For a theme object you already have (a downloaded `*.theme.json`), use
+`markersFromTheme(theme)`. Both it and `markersFromThemeUrl` return
+`undefined` when the theme carries no markers block, so "no markers" stays
+distinguishable from "an empty designed set"; `parseMarkers(value)` is the
+same lenient parse over a raw `extra.markers` value.
+
+```ts
+layer.setMarkers(block);   // replace - never dropped, even mid-style-load
+layer.setMarkers(undefined); // clear the markers, keep the layer alive
+layer.current;             // the parsed items
+layer.ids;                 // { source: "mm-user-markers", layer: "mm-user-markers" }
+layer.clear();             // remove layer, source and this layer's images
+layer.destroy();           // clear() + detach the style.load listener
+```
+
+- **One source, one layer**, both id `mm-user-markers` (a locked contract
+  shared with Studio and the server-side validator). `ids` is public API
+  for escape-hatch styling.
+- **Item fields**: `id` (unique, ≤ 64 characters), `lng`/`lat`, `icon` (one
+  of 21 glyphs, default `pin`; `dot` draws a plain circle), `colour`
+  (`#rrggbb`, default `#1a6bff`), `size` (`s`/`m`/`l` = 24/32/40 px,
+  default `m`), `label` (≤ 120 characters), `image` (a `data:` URI -
+  png/jpeg/webp/svg+xml, base64, ≤ 64 KB decoded - drawn instead of the
+  pin). Lengths are counted in Unicode scalars, so emoji count as one.
+- **Parsing is lenient and never throws**: invalid items are skipped, bad
+  fields fall back to defaults, over-long labels are truncated. A block
+  whose `version` is not `1` parses to nothing at all - a future v2 must
+  not be silently drawn as v1 by an already-installed SDK.
+- **Custom images load asynchronously**: the marker draws its glyph pin
+  until the image arrives, then swaps in place. An image MapLibre cannot
+  rasterise keeps the pin - pass `{ onImageError }` to hear about it rather
+  than wondering why a logo is a blue pin:
+
+  ```ts
+  new MarkersLayer(map, markers, {
+    onImageError: (image, error) => console.warn("marker image", image, error),
+  });
+  ```
+
+  The usual cause is an **SVG with no intrinsic `width`/`height`**: an
+  `<img>` renders it happily, `createImageBitmap` (what `map.loadImage`
+  uses) refuses it.
+- **Labels need the `MapMap Sans Regular` fontstack** from the style's
+  `glyphs` endpoint, exactly like the places labels above; a custom glyphs
+  host without it drops the labels silently.
+- The layer **survives `setStyle`** and re-installs itself on every
+  `style.load`. That is load-bearing: MapLibre diffs against a serialised
+  style that INCLUDES runtime sources/layers, so a diffed `setStyle`
+  removes `mm-user-markers` and the `style.load` that `setState` fires
+  afterwards is what puts it back.
 
 ### `class NavigationCamera`
 
@@ -304,6 +472,14 @@ const map = new MapMapMap({
 - **`extra.nav`** (Studio's navigation design block) is carried by the theme
   file and ignored by style compilation - see "Using your Studio design"
   below.
+- **`extra.markers`** (Studio's custom markers & labels, schema v1) rides
+  the same way: `{ "version": 1, "items": [ { "id", "lng", "lat", "icon",
+  "colour", "size", "label", "image" } ] }`, up to 200 items, never part of
+  the compiled `style.json`. Read it with `markersFromTheme(theme)` /
+  `markersFromThemeUrl(url)` and draw it with `MarkersLayer` (above).
+  `extra` as a whole is bounded at 256 KB serialised, and each marker
+  `image` at 64 KB decoded - the per-image caps multiply, so a few
+  full-size marker images will hit the block cap first.
 - **Layer ids** (29, paint order): `background landcover landuse park water
   waterway aeroway building building-outline rail pedestrian-areas road-path
   road-minor-casing road-major-casing road-minor road-major
@@ -622,12 +798,14 @@ mapping. Available from the main entry and as a separate
 ```ts
 import {
   directionIcons,          // { turn_left: "<svg…>", roundabout_right: …, ferry: … }
-  iconNameForStep,         // (step) => DirectionIconName — preferred
+  iconNamesForSteps,       // (steps) => DirectionIconName[] — preferred for a turn list
+  iconNameForStep,         // (step) => DirectionIconName
   iconNameForManeuver,     // (type?, modifier?, drivingSide?) => DirectionIconName
   directionIconSvg,        // shorthand: the SVG for a maneuver
 } from "@mapmap/maps/direction-icons";
 
-el.innerHTML = directionIcons[iconNameForStep(step)];
+const icons = iconNamesForSteps(leg.steps);
+el.innerHTML = directionIcons[icons[i]];
 ```
 
 Icons are 20×20 `viewBox` SVGs. The arrow inherits `currentColor`; secondary
@@ -636,8 +814,19 @@ 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.
 
-Prefer `iconNameForStep(step)`: it reads everything off the OSRM step
-itself — ferry legs from `step.mode`, and the u-turn direction from
+Rendering a turn list? Use `iconNamesForSteps(steps)`. A roundabout's icon
+has to be read from the manoeuvre's THROUGH angle — the turn between the
+road you arrive on and the road you leave on — and no single step carries
+that: the enter step knows the approach, the matching exit step knows the
+road taken. Resolve them together and consecutive roundabouts render
+distinct icons; resolve them one at a time and every roundabout on the
+route draws the same generic ring. (Stock OSRM does send a roundabout
+`modifier`, but it measures the entry tangent, which is "left" for every
+roundabout in a left-hand-traffic country — `iconNamesForSteps`
+deliberately overrides it.)
+
+For a single step, `iconNameForStep(step)` 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

package/dist/{chunk-CH53LJR7.js → chunk-J657OWYE.js}

@@ -150,7 +150,40 @@ function iconNameForStep(step) {
   const side = step.driving_side === "left" ? "left" : "right";
   return iconNameForManeuver(step.maneuver?.type, step.maneuver?.modifier, side);
 }
+var ROUNDABOUT_ENTER = /* @__PURE__ */ new Set(["roundabout", "rotary"]);
+var ROUNDABOUT_EXIT = /* @__PURE__ */ new Set(["exit roundabout", "exit rotary"]);
+function signedTurn(from, to) {
+  return ((to - from + 180) % 360 + 360) % 360 - 180;
+}
+function modifierForTurn(delta) {
+  const magnitude = Math.abs(delta);
+  if (magnitude <= 22.5) return "straight";
+  const side = delta < 0 ? "left" : "right";
+  if (magnitude <= 67.5) return `slight ${side}`;
+  if (magnitude <= 112.5) return side;
+  return `sharp ${side}`;
+}
+function iconNamesForSteps(steps) {
+  const names = steps.map((step) => iconNameForStep(step));
+  const norm = (s) => (s ?? "").trim().toLowerCase();
+  for (let i = 0; i < steps.length - 1; i += 1) {
+    const enter = steps[i]?.maneuver;
+    const exit = steps[i + 1]?.maneuver;
+    if (!enter || !exit) continue;
+    if (!ROUNDABOUT_ENTER.has(norm(enter.type))) continue;
+    if (!ROUNDABOUT_EXIT.has(norm(exit.type))) continue;
+    const approach = enter.bearing_before;
+    const taken = exit.bearing_after;
+    if (typeof approach !== "number" || !Number.isFinite(approach)) continue;
+    if (typeof taken !== "number" || !Number.isFinite(taken)) continue;
+    if (approach === 0 && enter.bearing_after === 0) continue;
+    const modifier = modifierForTurn(signedTurn(approach, taken));
+    names[i] = iconNameForManeuver(enter.type, modifier);
+    names[i + 1] = iconNameForManeuver(exit.type, modifier);
+  }
+  return names;
+}
 
-export { directionIconSvg, directionIcons, iconNameForManeuver, iconNameForStep };
-//# sourceMappingURL=chunk-CH53LJR7.js.map
-//# sourceMappingURL=chunk-CH53LJR7.js.map
+export { directionIconSvg, directionIcons, iconNameForManeuver, iconNameForStep, iconNamesForSteps };
+//# sourceMappingURL=chunk-J657OWYE.js.map
+//# sourceMappingURL=chunk-J657OWYE.js.map