@diagrammo/dgmo 0.21.0 → 0.21.1

package/src/map/renderer.ts

@@ -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
@@ -347,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`. */
@@ -47,6 +51,8 @@ export interface ResolvedRegion {
   readonly name: string; // display name
   readonly layer: 'country' | 'us-state';
   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;

package/src/map/resolver.ts

@@ -18,7 +18,13 @@ import type {
   ProjectionFamily,
   GeoExtent,
 } from './resolved-types';
-import { featureIndex, featureBbox, unionExtent, fold } from './geo';
+import {
+  featureIndex,
+  featureBbox,
+  featureBboxPrimary,
+  unionExtent,
+  fold,
+} from './geo';
 
 /** Discriminated result of a gazetteer name lookup (#5): `defer` is "ambiguous,
  *  retry in pass B with inferred scope" — distinct from `miss` (errored, drop) so
@@ -30,7 +36,13 @@ type LookupResult =
 
 // Projection / tier thresholds (degrees of span) — tunable (R10).
 const WORLD_SPAN = 90;
-const MERCATOR_MAX_SPAN = 25;
+// Mercator is used for everything sub-world (tight clusters AND single-continent
+// regional views — a mid-latitude continent reads with its familiar conventional
+// shape, where equirectangular squashes it). Two guards push back to
+// equirectangular: a world/multi-continent `span` (> WORLD_SPAN), or a frame that
+// reaches into polar latitudes (> MERCATOR_MAX_LAT) where Mercator's sec(φ) area
+// blow-up turns gross. Europe (≈71°N) and East Asia stay comfortably on Mercator.
+const MERCATOR_MAX_LAT = 80;
 const PAD_FRACTION = 0.05;
 // Latitude band for a snapped world view — Tierra del Fuego (≈ −55°) to northern
 // Russia/Canada (≈ +78°). Excludes most of Antarctica + the high Arctic so the
@@ -255,17 +267,19 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
       }
     } else if (inCountry && inState) {
       if (usScoped) {
+        // A US scope (e.g. `region us-states`) makes the state the unambiguous
+        // intent — resolve silently, no disambiguation warning needed.
         chosen = { ...inState, layer: 'us-state' };
       } else {
         chosen = { ...inCountry, layer: 'country' };
+        // Teach the disambiguation syntax so the author can pin it explicitly.
+        // Suggest the non-redundant forms: a bare ISO code, or name + scope.
+        warn(
+          r.lineNumber,
+          `"${r.name}" is both a country and a US state — resolved as ${chosen.layer} (${chosen.id}). Pin it with an ISO code (${inState.id} / ${inCountry.id}) or name + scope ("${r.name} US" / "${r.name} ${inCountry.id}").`,
+          'W_MAP_REGION_AMBIGUOUS'
+        );
       }
-      // Teach the disambiguation syntax so the author can pin it explicitly.
-      // Suggest the non-redundant forms: a bare ISO code, or name + scope.
-      warn(
-        r.lineNumber,
-        `"${r.name}" is both a country and a US state — resolved as ${chosen.layer} (${chosen.id}). Pin it with an ISO code (${inState.id} / ${inCountry.id}) or name + scope ("${r.name} US" / "${r.name} ${inCountry.id}").`,
-        'W_MAP_REGION_AMBIGUOUS'
-      );
     } else if (inState) {
       chosen = { ...inState, layer: 'us-state' };
     } else if (inCountry) {
@@ -289,6 +303,7 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
       name: chosen.name,
       layer: chosen.layer,
       ...(r.value !== undefined && { value: r.value }),
+      ...(r.color !== undefined && { color: r.color }),
       tags: r.tags,
       meta: r.meta,
       lineNumber: r.lineNumber,
@@ -476,6 +491,7 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
       lat,
       lon,
       ...(p.label !== undefined && { label: p.label }),
+      ...(p.color !== undefined && { color: p.color }),
       tags: p.tags,
       meta: p.meta,
       lineNumber: p.lineNumber,
@@ -643,10 +659,12 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
     const bb = featureBbox(data.usStates, ref.id);
     if (bb) regionBoxes.push(bb);
   }
-  // country regions contribute their country bbox
+  // country regions contribute their country bbox — but framed on the dominant
+  // landmass, ignoring far-detached minor territories (e.g. French Guiana) so a
+  // Europe map naming France doesn't auto-fit across the Atlantic (R5).
   for (const r of regions) {
     if (r.layer === 'country') {
-      const bb = featureBbox(data.worldCoarse, r.iso);
+      const bb = featureBboxPrimary(data.worldCoarse, r.iso);
       if (bb) regionBoxes.push(bb);
     }
   }
@@ -661,6 +679,7 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
   const lonSpan = extent[1][0] - extent[0][0];
   const latSpan = extent[1][1] - extent[0][1];
   const span = Math.max(lonSpan, latSpan);
+  const maxAbsLat = Math.max(Math.abs(extent[0][1]), Math.abs(extent[1][1]));
   // albers-usa only covers US territory: choose it only when the map is truly
   // US-only — no non-US country region AND no POI outside the US (#13). Without
   // the POI guard a `default-country US` + Tokyo map projected to garbage.
@@ -687,16 +706,18 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
     projection = override;
   } else if (usDominant) {
     projection = 'albers-usa';
-  } else if (span > WORLD_SPAN) {
-    // World/continental scale: equirectangular fills the frame edge-to-edge and
-    // never clips the continents at the boundary (naturalEarth's curved sides
-    // overrun a corner-based fit). `projection natural-earth` opts back into the
-    // curved look explicitly.
+  } else if (span > WORLD_SPAN || maxAbsLat > MERCATOR_MAX_LAT) {
+    // World/multi-continent scale (or a polar-reaching frame): equirectangular
+    // fills the frame edge-to-edge, never clips the continents at the boundary
+    // (naturalEarth's curved sides overrun a corner-based fit), and avoids
+    // Mercator's gross sec(φ) area blow-up near the poles. `projection
+    // natural-earth` opts back into the curved look explicitly.
     projection = 'equirectangular';
-  } else if (span < MERCATOR_MAX_SPAN) {
-    projection = 'mercator';
   } else {
-    projection = 'equirectangular';
+    // Tight clusters AND single-continent regional views: Mercator gives every
+    // mid-latitude landmass its familiar conventional shape (equirectangular
+    // squashes a continent like Europe horizontally).
+    projection = 'mercator';
   }
 
   // World-scale framing (R10): a multi-continent spread frames most cleanly as

package/src/map/types.ts

@@ -23,6 +23,9 @@ export interface MapDirectives {
   projection?: string;
   /** Legend label for the region value ramp (`region-metric <label>`). */
   regionMetric?: string;
+  /** Recognized color NAME for the choropleth ramp hue, peeled off the
+   *  `region-metric` trailing token (§24B.3). Defaults to red when absent. */
+  regionMetricColor?: string;
   /** Legend label for the POI value (marker size) channel (`poi-metric`). */
   poiMetric?: string;
   /** Legend label for the edge/leg value (thickness) channel (`flow-metric`). */
@@ -34,6 +37,10 @@ export interface MapDirectives {
   defaultState?: string;
   activeTag?: string;
   noLegend?: boolean;
+  /** Suppress the Alaska & Hawaii inset boxes drawn under the `albers-usa`
+   *  projection (bare flag `no-insets`). Only meaningful for the US states
+   *  basemap; silently ignored under any other projection. */
+  noInsets?: boolean;
   subtitle?: string;
   caption?: string;
   /** Basemap dress override (bare flags `muted` / `natural`). Forces the
@@ -42,6 +49,11 @@ export interface MapDirectives {
    *  dress. Absent → auto (muted iff a score/tag dimension is active). Lets two
    *  maps in one deck share a look. */
   basemapStyle?: 'muted' | 'natural';
+  /** Opt-in subtle mountain-range relief shading (bare flag `relief`, §24B.2).
+   *  Draws a shared directional gradient ("degenerate hillshade") clipped to
+   *  each notable mountain-range polygon, over base land and under data fills.
+   *  Off by default; needs the optional `mountain-ranges.json` asset. */
+  relief?: boolean;
 }
 
 /** A region-fill: a subdivision name with an optional score and/or tag values
@@ -54,6 +66,9 @@ export interface MapRegion {
   readonly scope?: string;
   /** Numeric value → choropleth shade (§24B.3). Lifted out of `meta`. */
   readonly value?: number;
+  /** §1.5 trailing-token color NAME → flat categorical override fill (§24B.4);
+   *  painted regardless of the active colouring dimension, no legend entry. */
+  readonly color?: string;
   /** Tag values keyed by lowercased tag GROUP name (alias is resolved away). */
   readonly tags: Readonly<Record<string, string>>;
   /** Any remaining reserved keys captured verbatim (`label`/`style`/…). */
@@ -67,6 +82,9 @@ export interface MapPoi {
   readonly pos: PoiPos;
   readonly alias?: string;
   readonly label?: string;
+  /** §1.5 trailing-token color NAME → flat marker fill (§24B.5); wins over a
+   *  tag color and the default orange. */
+  readonly color?: string;
   readonly tags: Readonly<Record<string, string>>;
   readonly meta: Readonly<Record<string, string>>;
   readonly lineNumber: number;