@diagrammo/dgmo 0.20.3 → 0.21.1

package/src/map/load-data.ts

@@ -43,6 +43,7 @@ const FILES = {
   usStates: 'us-states.json',
   lakes: 'lakes.json',
   rivers: 'rivers.json',
+  mountainRanges: 'mountain-ranges.json',
   naLand: 'na-land.json',
   naLakes: 'na-lakes.json',
   gazetteer: 'gazetteer.json',
@@ -131,6 +132,7 @@ export function loadMapData(): Promise<MapData> {
       usStates,
       lakes,
       rivers,
+      mountainRanges,
       naLand,
       naLakes,
       gazetteer,
@@ -138,9 +140,12 @@ export function loadMapData(): Promise<MapData> {
       readJson<BoundaryTopology>(nb, dir, FILES.worldCoarse),
       readJson<BoundaryTopology>(nb, dir, FILES.worldDetail),
       readJson<BoundaryTopology>(nb, dir, FILES.usStates),
-      // Lakes/rivers/NA assets are optional — older bundles may predate them.
+      // Lakes/rivers/mountain/NA assets are optional — older bundles may predate them.
       readJson<BoundaryTopology>(nb, dir, FILES.lakes).catch(() => undefined),
       readJson<BoundaryTopology>(nb, dir, FILES.rivers).catch(() => undefined),
+      readJson<BoundaryTopology>(nb, dir, FILES.mountainRanges).catch(
+        () => undefined
+      ),
       readJson<BoundaryTopology>(nb, dir, FILES.naLand).catch(() => undefined),
       readJson<BoundaryTopology>(nb, dir, FILES.naLakes).catch(() => undefined),
       readJson<Gazetteer>(nb, dir, FILES.gazetteer),
@@ -152,6 +157,7 @@ export function loadMapData(): Promise<MapData> {
       gazetteer,
       ...(lakes && { lakes }),
       ...(rivers && { rivers }),
+      ...(mountainRanges && { mountainRanges }),
       ...(naLand && { naLand }),
       ...(naLakes && { naLakes }),
     });

package/src/map/parser.ts

@@ -9,6 +9,7 @@ import {
   measureIndent,
   splitNameAndMeta,
   extractColor,
+  peelTrailingColorName,
 } from '../utils/parsing';
 import {
   MAP_REGISTRY,
@@ -28,7 +29,7 @@ import type {
   MapRegion,
   MapPoi,
   MapRoute,
-  MapRouteStop,
+  MapRouteLeg,
   MapEdge,
   PoiPos,
   MapScale,
@@ -42,13 +43,16 @@ const SCOPE_RE = /^[A-Z]{2}(?:-[A-Z0-9]{1,3})?$/;
 // whitespace, so hyphens inside names (`office-east`) and `foo-bar` are safe.
 const ARROW_SPLIT = /\s+(-[^>]*?->|->|~[^>]*?~>|~>|--)\s+/;
 const HUB_RE = /^(->|~>)\s+(.+)$/;
+// A route leg line: an optional leading arrow (with in-arrow label) + a destination.
+const LEG_ARROW_RE = /^(-[^>]*?->|->|~[^>]*?~>|~>|--)\s+(.+)$/;
 const AT_RE = /(^|[\s,])at\s*:/i; // the removed `at:` coord form (§24B.9)
 
 const DIRECTIVE_SET: ReadonlySet<string> = new Set([
   'region',
   'projection',
-  'metric',
-  'size-metric',
+  'region-metric',
+  'poi-metric',
+  'flow-metric',
   'scale',
   'region-labels',
   'poi-labels',
@@ -56,6 +60,8 @@ const DIRECTIVE_SET: ReadonlySet<string> = new Set([
   'default-state',
   'active-tag',
   'no-legend',
+  'no-insets',
+  'relief',
   'subtitle',
   'caption',
 ]);
@@ -177,9 +183,10 @@ export function parseMap(content: string): ParsedMap {
       addTagEntry(open.tag, trimmed, lineNumber);
       continue;
     }
-    // (1a) Indented child of an open route → a stop.
+    // (1a) Indented child of an open route → a leg (an edge from the prev stop).
     if (open.route && indent > open.route.indent) {
-      open.route.route.stops.push(parseStop(trimmed, lineNumber));
+      const leg = parseLeg(trimmed, lineNumber, open.route.route.style);
+      (open.route.route.legs as MapRouteLeg[]).push(leg);
       continue;
     }
     // (1b) Indented child of an open POI → hub edge or extra metadata.
@@ -217,6 +224,15 @@ export function parseMap(content: string): ParsedMap {
       handleTag(trimmed, lineNumber);
       continue;
     }
+    // Bare-flag directives (no value) — only when the line is exactly the flag,
+    // so a region named e.g. "Natural Bridge" still parses as a region.
+    if (
+      (firstWord === 'muted' || firstWord === 'natural') &&
+      trimmed === firstWord
+    ) {
+      handleDirective(firstWord, '', lineNumber);
+      continue;
+    }
     if (
       DIRECTIVE_SET.has(firstWord) &&
       !trimmed.slice(firstWord.length).trimStart().startsWith(':')
@@ -297,13 +313,23 @@ export function parseMap(content: string): ParsedMap {
           );
         d.projection = value;
         break;
-      case 'metric':
-        dup(d.metric);
-        d.metric = value;
+      case 'region-metric': {
+        dup(d.regionMetric);
+        // A trailing color names the choropleth ramp hue (§24B.3): the
+        // label keeps the rest. `region-metric Sales ($M) blue` → blue ramp.
+        const { label: rmLabel, colorName: rmColor } =
+          peelTrailingColorName(value);
+        d.regionMetric = rmLabel;
+        if (rmColor) d.regionMetricColor = rmColor;
         break;
-      case 'size-metric':
-        dup(d.sizeMetric);
-        d.sizeMetric = value;
+      }
+      case 'poi-metric':
+        dup(d.poiMetric);
+        d.poiMetric = value;
+        break;
+      case 'flow-metric':
+        dup(d.flowMetric);
+        d.flowMetric = value;
         break;
       case 'scale':
         dup(d.scale);
@@ -345,6 +371,22 @@ export function parseMap(content: string): ParsedMap {
       case 'no-legend':
         d.noLegend = true;
         break;
+      case 'no-insets':
+        d.noInsets = true;
+        break;
+      case 'relief':
+        // Bare flag (idempotent like no-insets — `relief\nrelief` is no warning).
+        d.relief = true;
+        break;
+      case 'muted':
+      case 'natural':
+        if (d.basemapStyle !== undefined && d.basemapStyle !== key)
+          pushWarning(
+            line,
+            `Conflicting basemap dress — "${d.basemapStyle}" then "${key}"; last wins.`
+          );
+        d.basemapStyle = key;
+        break;
       case 'subtitle':
         dup(d.subtitle);
         d.subtitle = value;
@@ -431,18 +473,18 @@ export function parseMap(content: string): ParsedMap {
       line
     );
     const { tags, meta } = partitionMeta(split.meta, tagGroupNames());
-    let scoreNum: number | undefined;
-    const score = meta['score'];
-    if (score !== undefined) {
-      delete (meta as Record<string, string>)['score']; // lifted out of inert meta
-      scoreNum = Number(score);
-      if (!Number.isFinite(scoreNum)) {
-        pushError(line, `score must be a number (got "${score}").`);
-        scoreNum = undefined;
+    let valueNum: number | undefined;
+    const value = meta['value'];
+    if (value !== undefined) {
+      delete (meta as Record<string, string>)['value']; // lifted out of meta
+      valueNum = Number(value);
+      if (!Number.isFinite(valueNum)) {
+        pushError(line, `value must be a number (got "${value}").`);
+        valueNum = undefined;
       }
     }
-    // A region may carry BOTH a `score:` and a tag value — they are two
-    // selectable colouring dimensions (the legend flips between the score ramp
+    // A region may carry BOTH a `value:` and a tag value — they are two
+    // selectable colouring dimensions (the legend flips between the value ramp
     // and the tag group), so this is no longer warned (bivariate is handled).
     // Peel a trailing ISO scope token (§24B.8) — same qualifier POIs accept,
     // so `Georgia US-GA` / `Georgia US` can force the country-vs-state pick.
@@ -461,7 +503,9 @@ export function parseMap(content: string): ParsedMap {
       lineNumber: line,
     };
     if (regionScope !== undefined) region.scope = regionScope;
-    if (scoreNum !== undefined) region.score = scoreNum;
+    if (valueNum !== undefined) region.value = valueNum;
+    // §1.5 trailing color → flat categorical override fill (§24B.4).
+    if (split.color) region.color = split.color;
     regions.push(region);
   }
 
@@ -482,35 +526,100 @@ export function parseMap(content: string): ParsedMap {
     const pos = parsePos(split.name, line);
     if (!pos) return; // error already pushed
     const { tags, meta } = partitionMeta(split.meta, tagGroupNames());
-    const label = meta['label']; // label lifted out of meta; `score`/`size`/`date` stay inert (#2)
+    const label = meta['label']; // label lifted out of meta; `value` (→ marker size) stays in meta
     if (label !== undefined) delete (meta as Record<string, string>)['label'];
     const poi: Writable<MapPoi> = { pos, tags, meta, lineNumber: line };
     if (split.alias) poi.alias = split.alias;
     if (label !== undefined) poi.label = label;
+    // §1.5 trailing color → flat marker fill (§24B.5); wins over a tag color.
+    if (split.color) poi.color = split.color;
     pois.push(poi);
     open.poi = { poi, indent };
   }
 
   function handleRoute(rest: string, line: number, indent: number): void {
-    const meta = rest ? splitNameAndMeta(rest, registry(), aliasMap).meta : {};
-    const route: Writable<MapRoute> = { stops: [], meta, lineNumber: line };
+    const split = rest
+      ? splitNameAndMeta(
+          rest,
+          registry(),
+          aliasMap,
+          undefined,
+          diagnostics,
+          line
+        )
+      : { name: '', meta: {} as Record<string, string>, alias: undefined };
+    const pos = parsePos(split.name, line);
+    if (!pos || (pos.kind === 'name' && !pos.name)) {
+      pushError(
+        line,
+        'route requires an origin: `route <origin> [style: arc]`.'
+      );
+      return;
+    }
+    const { tags, meta } = partitionMeta(split.meta, tagGroupNames());
+    const originLabel = meta['label'];
+    const originValue = meta['value'];
+    const style: 'straight' | 'arc' =
+      meta['style'] === 'arc' ? 'arc' : 'straight';
+    const route: Writable<MapRoute> = {
+      origin: pos,
+      ...(split.alias !== undefined && { originAlias: split.alias }),
+      ...(originLabel !== undefined && { originLabel }),
+      ...(originValue !== undefined && { originValue }),
+      originTags: tags,
+      style,
+      legs: [],
+      lineNumber: line,
+    };
     routes.push(route);
     open.route = { route, indent };
   }
 
-  function parseStop(trimmed: string, line: number): MapRouteStop {
-    const split = splitNameAndMeta(trimmed, registry(), aliasMap);
-    const ref = parsePos(split.name, line) ?? {
+  /** Parse one route body line into a leg: `[-label->] <destination> [keys]`.
+   *  The arrow (if any) gives the leg label + shape; `value:` is leg thickness;
+   *  a tag / `label:` decorate the destination stop. Bare `<dest>` = plain leg. */
+  function parseLeg(
+    trimmed: string,
+    line: number,
+    headerStyle: 'straight' | 'arc'
+  ): MapRouteLeg {
+    let arrowStyle: 'straight' | 'arc' = 'straight';
+    let label: string | undefined;
+    let rest = trimmed;
+    const m = trimmed.match(LEG_ARROW_RE);
+    if (m) {
+      const arr = classifyArrow(m[1]!, line);
+      arrowStyle = arr.style;
+      label = arr.label;
+      rest = m[2]!;
+    }
+    const split = splitNameAndMeta(
+      rest,
+      registry(),
+      aliasMap,
+      undefined,
+      diagnostics,
+      line
+    );
+    const pos = parsePos(split.name, line) ?? {
       kind: 'name',
       name: split.name,
     };
-    const stop: Writable<MapRouteStop> = {
-      ref,
-      meta: split.meta,
+    const { tags, meta } = partitionMeta(split.meta, tagGroupNames());
+    const value = meta['value'];
+    const destLabel = meta['label'];
+    const style: 'straight' | 'arc' =
+      arrowStyle === 'arc' || headerStyle === 'arc' ? 'arc' : 'straight';
+    return {
+      ...(label !== undefined && { label }),
+      style,
+      ...(value !== undefined && { value }),
+      dest: pos,
+      ...(split.alias !== undefined && { destAlias: split.alias }),
+      ...(destLabel !== undefined && { destLabel }),
+      destTags: tags,
       lineNumber: line,
     };
-    if (split.alias) stop.alias = split.alias;
-    return stop;
   }
 
   function handleEdges(trimmed: string, line: number): void {

package/src/map/renderer.ts

@@ -101,11 +101,11 @@ export function renderMap(
       .attr('stroke', r.stroke)
       .attr('stroke-width', strokeWidth);
     // Data layer? Tag it so the app can highlight on legend hover / gradient
-    // scrub. `data-score` for ramp-proximity, `data-tag-<group>` per tag value
+    // scrub. `data-value` for ramp-proximity, `data-tag-<group>` per tag value
     // (both lowercased to match the lowercased legend-entry attributes).
     if (r.layer !== 'base') {
       p.classed('dgmo-map-region', true).attr('data-region', r.id);
-      if (r.score !== undefined) p.attr('data-score', r.score);
+      if (r.value !== undefined) p.attr('data-value', r.value);
       if (r.tags) {
         for (const [group, value] of Object.entries(r.tags)) {
           p.attr(`data-tag-${group.toLowerCase()}`, value.toLowerCase());
@@ -123,6 +123,49 @@ export function renderMap(
   };
   for (const r of layout.regions) drawRegion(gRegions, r, 0.5);
 
+  // ── Relief (mountain-range hachure over ALL land, under rivers/POIs/labels) ──
+  // Rule horizontal lines across the whole canvas, clipped to the INTERSECTION
+  // of (a) the union of range polygons and (b) the land — nested clipPaths, so
+  // the hachure never bleeds onto water (coarse range polygons overrun the
+  // coast, and horizontal lines on the sea read as the water convention). The
+  // land clip is every drawn region except lakes — INCLUDING value-/tag-coloured
+  // regions, so the relief texture sits ATOP the choropleth/tag fills (a range
+  // crossing a valued state still reads as mountains there). It stays below
+  // rivers, POIs, and labels. Explicit <line>s in a <clipPath> (not a tiled
+  // <pattern>) dodge WKWebView/resvg pattern quirks. A non-scaling stroke keeps
+  // the width constant in device px at any zoom/DPR (uniform, no moire); kept
+  // sub-pixel + low-contrast so the texture stays faint. Decorative — no data attrs.
+  if (layout.relief.length && layout.reliefHatch) {
+    const h = layout.reliefHatch;
+    const rangeClipId = 'dgmo-relief-clip';
+    const landClipId = 'dgmo-relief-land';
+    const rangeClip = defs.append('clipPath').attr('id', rangeClipId);
+    for (const s of layout.relief) rangeClip.append('path').attr('d', s.d);
+    const landClip = defs.append('clipPath').attr('id', landClipId);
+    for (const r of layout.regions)
+      if (r.id !== 'lake') landClip.append('path').attr('d', r.d);
+    const gRelief = svg
+      .append('g')
+      .attr('clip-path', `url(#${landClipId})`) // outer: land only
+      .append('g')
+      .attr('class', 'dgmo-map-relief')
+      .attr('clip-path', `url(#${rangeClipId})`) // inner: ∩ ranges
+      .attr('stroke', h.color)
+      .attr('stroke-width', h.width)
+      // Non-scaling stroke = constant device width at any zoom/DPR (uniform,
+      // no moire). NOT crispEdges — that snaps to a solid ~1px in WebKit and
+      // reads far too heavy; plain AA keeps the sub-pixel lines whisper-thin.
+      .attr('vector-effect', 'non-scaling-stroke');
+    for (let y = h.spacing; y < height; y += h.spacing) {
+      gRelief
+        .append('line')
+        .attr('x1', 0)
+        .attr('y1', y)
+        .attr('x2', width)
+        .attr('y2', y);
+    }
+  }
+
   // ── Rivers (thin water centerlines over the land, under POIs/edges) ──
   if (layout.rivers.length) {
     const gRivers = svg
@@ -230,6 +273,13 @@ export function renderMap(
       .attr('stroke-width', 1)
       .attr('data-line-number', poi.lineNumber)
       .attr('data-poi', poi.id);
+    // Tag the marker per tag value (lowercased, matching the lowercased
+    // legend-entry attributes) so the app can spotlight it on legend hover.
+    if (poi.tags) {
+      for (const [group, value] of Object.entries(poi.tags)) {
+        c.attr(`data-tag-${group.toLowerCase()}`, value.toLowerCase());
+      }
+    }
     if (onClickItem) {
       c.style('cursor', 'pointer').on('click', () =>
         onClickItem(poi.lineNumber)
@@ -296,14 +346,14 @@ export function renderMap(
       .append('g')
       .attr('class', 'dgmo-map-legend')
       .attr('transform', `translate(0, ${legendY})`);
-    // The score ramp is a selectable colouring group alongside the tag groups
+    // The value ramp is a selectable colouring group alongside the tag groups
     // (the user flips between them); its capsule renders the gradient inline.
-    // Reserved name "Score" when no metric label is set — must match SCORE_NAME
-    // in layout.ts so the resolved activeGroup selects it.
+    // Reserved name "Value" when no region-metric label is set — must match
+    // VALUE_NAME in layout.ts so the resolved activeGroup selects it.
     const ramp = layout.legend.ramp;
     const scoreGroup = ramp
       ? {
-          name: ramp.metric?.trim() || 'Score',
+          name: ramp.metric?.trim() || 'Value',
           entries: [],
           gradient: {
             min: ramp.min,
@@ -340,6 +390,7 @@ export function renderMap(
   if (layout.title) {
     svg
       .append('text')
+      .attr('class', 'dgmo-map-title')
       .attr('x', width / 2)
       .attr('y', TITLE_Y)
       .attr('text-anchor', 'middle')

package/src/map/resolved-types.ts

@@ -17,6 +17,10 @@ export interface MapData {
   /** Major river centerlines (Natural Earth 110m) drawn as thin water lines over
    *  land — e.g. the Amazon, Nile, Mississippi. Optional, like `lakes`. */
   rivers?: BoundaryTopology;
+  /** Notable mountain-range polygons (Natural Earth 50m geography regions) drawn
+   *  as a subtle gradient relief cue over base land when the `relief` directive
+   *  is on — e.g. the Rockies, Andes, Himalayas. Optional, like `lakes`. */
+  mountainRanges?: BoundaryTopology;
   /** North-America-clipped 10m country land, used as crisp neighbour context
    *  under the albers-usa US view so Canada/Mexico match the 10m states instead
    *  of the coarser world tiers. Optional, like `lakes`. */
@@ -46,7 +50,9 @@ export interface ResolvedRegion {
   readonly iso: string;
   readonly name: string; // display name
   readonly layer: 'country' | 'us-state';
-  readonly score?: number;
+  readonly value?: number;
+  /** §1.5 trailing-token color NAME → flat override fill (§24B.4). */
+  readonly color?: string;
   readonly tags: Readonly<Record<string, string>>;
   readonly meta: Readonly<Record<string, string>>;
   readonly lineNumber: number;
@@ -62,6 +68,8 @@ export interface ResolvedPoi {
   readonly lat: number;
   readonly lon: number;
   readonly label?: string;
+  /** §1.5 trailing-token color NAME → flat marker fill (§24B.5). */
+  readonly color?: string;
   readonly tags: Readonly<Record<string, string>>;
   readonly meta: Readonly<Record<string, string>>;
   readonly lineNumber: number;
@@ -79,9 +87,20 @@ export interface ResolvedEdge {
   readonly lineNumber: number;
 }
 
+export interface ResolvedRouteLeg {
+  readonly fromId: string;
+  readonly toId: string;
+  readonly label?: string;
+  readonly style: 'straight' | 'arc';
+  readonly value?: string; // leg thickness
+  readonly lineNumber: number;
+}
+
 export interface ResolvedRoute {
+  /** Ordered UNIQUE stop ids (for numbering + the origin marker). A loop-closing
+   *  leg whose destination is an earlier stop adds a leg but no duplicate stop. */
   readonly stopIds: readonly string[];
-  readonly meta: Readonly<Record<string, string>>;
+  readonly legs: readonly ResolvedRouteLeg[];
   readonly lineNumber: number;
 }