@diagrammo/dgmo 0.19.0 → 0.20.0

package/src/map/resolved-types.ts

@@ -11,10 +11,27 @@ export interface MapData {
   worldCoarse: BoundaryTopology;
   worldDetail: BoundaryTopology;
   usStates: BoundaryTopology;
+  /** Major lakes (Natural Earth 110m) drawn as water over land — e.g. the Great
+   *  Lakes. Optional so hand-built test fixtures need not supply it. */
+  lakes?: BoundaryTopology;
+  /** Major river centerlines (Natural Earth 110m) drawn as thin water lines over
+   *  land — e.g. the Amazon, Nile, Mississippi. Optional, like `lakes`. */
+  rivers?: 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`. */
+  naLand?: BoundaryTopology;
+  /** North-America-clipped 10m major lakes (Great Lakes etc.), used in place of
+   *  the coarse `lakes` under the albers-usa US view. Optional. */
+  naLakes?: BoundaryTopology;
   gazetteer: Gazetteer;
 }
 
-export type ProjectionFamily = 'natural-earth' | 'albers-usa' | 'mercator';
+export type ProjectionFamily =
+  | 'equirectangular'
+  | 'natural-earth'
+  | 'albers-usa'
+  | 'mercator';
 
 /** Which geometry layers the renderer draws. */
 export interface Basemaps {

package/src/map/resolver.ts

@@ -31,6 +31,11 @@ type LookupResult =
 const WORLD_SPAN = 90;
 const MERCATOR_MAX_SPAN = 25;
 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
+// populated continents fill the frame rather than waste it on ice.
+const WORLD_LAT_SOUTH = -58;
+const WORLD_LAT_NORTH = 78;
 
 // Long-form (or common-alias) country name → the folded Natural-Earth display
 // name actually shipped in world-coarse (#6). The NE coarse layer abbreviates a
@@ -122,6 +127,9 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
       const f = fold(r.name);
       return usStateIndex.has(f) && !countryIndex.has(f);
     }) ||
+    parsed.regions.some(
+      (r) => r.scope === 'US' || r.scope?.startsWith('US-')
+    ) ||
     parsed.pois.some(
       (p) => p.pos.kind === 'name' && p.pos.scope?.startsWith('US-')
     );
@@ -144,15 +152,42 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
       name: string;
       layer: 'country' | 'us-state';
     } | null = null;
-    if (inCountry && inState) {
+    // Explicit ISO scope (§24B.8): force the country-vs-state pick and skip the
+    // ambiguity warning. `US`/`US-XX` → state; any other 2-letter code → country.
+    const scope = r.scope;
+    if (scope) {
+      const wantsState = scope === 'US' || scope.startsWith('US-');
+      if (wantsState && inState) {
+        if (scope.startsWith('US-') && inState.id !== scope) {
+          err(
+            r.lineNumber,
+            `No subdivision "${r.name}" in scope ${scope} (it is ${inState.id}).`,
+            'E_MAP_SCOPE_MISS'
+          );
+          continue;
+        }
+        chosen = { ...inState, layer: 'us-state' };
+      } else if (!wantsState && inCountry) {
+        chosen = { ...inCountry, layer: 'country' };
+      } else {
+        err(
+          r.lineNumber,
+          `No region "${r.name}" found in scope ${scope}.`,
+          'E_MAP_SCOPE_MISS'
+        );
+        continue;
+      }
+    } else if (inCountry && inState) {
       if (usScoped) {
         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}).`,
+        `"${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) {
@@ -370,9 +405,23 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
   }
 
   // ── Edges + routes: bind endpoints, create implicit POIs (R7/R8) ──
+  // A POI declared with an alias (`poi Chicago as central`) registers under its
+  // id (`central`), so an endpoint that references it by NAME (`… -> Chicago`)
+  // misses the id registry. Map declared names → id so such a reference binds to
+  // the existing POI instead of spawning a duplicate implicit one on the same
+  // spot (only aliased POIs need this — a name-only POI's id already IS its
+  // folded name).
+  const declaredByName = new Map<string, string>();
+  for (const p of pois) {
+    const fn = p.name ? fold(p.name) : undefined;
+    if (fn && fn !== p.id && !declaredByName.has(fn))
+      declaredByName.set(fn, p.id);
+  }
   const resolveEndpoint = (ref: string, line: number): string | null => {
     const f = fold(ref);
     if (registry.has(f)) return f;
+    const aliased = declaredByName.get(f);
+    if (aliased) return aliased;
     const got = lookupName(ref, undefined, line, inferredCountry, true);
     if (got.kind !== 'ok') return null;
     noteCountry(got.iso);
@@ -462,9 +511,7 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
     [-180, -85],
     [180, 85],
   ];
-  const extent: GeoExtent = unioned
-    ? pad(unioned, PAD_FRACTION)
-    : DEFAULT_EXTENT; // empty → default
+  let extent: GeoExtent = unioned ? pad(unioned, PAD_FRACTION) : DEFAULT_EXTENT; // empty → default
 
   const lonSpan = extent[1][0] - extent[0][0];
   const latSpan = extent[1][1] - extent[0][1];
@@ -480,6 +527,7 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
   let projection: ProjectionFamily;
   const override = parsed.directives.projection;
   if (
+    override === 'equirectangular' ||
     override === 'natural-earth' ||
     override === 'albers-usa' ||
     override === 'mercator'
@@ -488,11 +536,35 @@ export function resolveMap(parsed: ParsedMap, data: MapData): ResolvedMap {
   } else if (usDominant) {
     projection = 'albers-usa';
   } else if (span > WORLD_SPAN) {
-    projection = 'natural-earth';
+    // 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.
+    projection = 'equirectangular';
   } else if (span < MERCATOR_MAX_SPAN) {
     projection = 'mercator';
   } else {
-    projection = 'natural-earth';
+    projection = 'equirectangular';
+  }
+
+  // World-scale framing (R10): a multi-continent spread frames most cleanly as
+  // the conventional Greenwich-centred world rectangle. The tight-arc longitude
+  // union is unstable for sparse global points — and an antimeridian-crossing
+  // country box (the US, via its Aleutians) wraps the union to an Asia-centred
+  // window that splits the Americas at the seam. When the data occupies at
+  // least half the globe in longitude, snap to full longitude AND widen the
+  // latitude band to the populated world (≈ Tierra del Fuego → northern
+  // Russia/Canada) so the map reads as a standard world view with every
+  // continent shown — not a thin band cropped to the data's latitudes (which
+  // would slice off South Africa, southern Argentina, northern Russia, …). The
+  // ≥180° gate leaves regional spreads tight — `region` continents (Europe
+  // ≈70°, Asia ≈155°) and antimeridian clusters (mercator anyway) untouched.
+  // Applies to both world projections (equirectangular default + natural-earth).
+  if (lonSpan >= 180) {
+    extent = [
+      [-180, Math.min(extent[0][1], WORLD_LAT_SOUTH)],
+      [180, Math.max(extent[1][1], WORLD_LAT_NORTH)],
+    ];
   }
 
   result.regions = regions;

package/src/map/types.ts

@@ -38,6 +38,10 @@ export interface MapDirectives {
  *  (§24B.3/.4 — BOTH may be present; bivariate seam). */
 export interface MapRegion {
   readonly name: string;
+  /** Optional trailing ISO scope qualifier (§24B.8) — a 3166-1 country code
+   *  (`Georgia US` → US context) or 3166-2 subdivision (`Georgia US-GA`).
+   *  Forces the country-vs-state interpretation and silences the ambiguity warning. */
+  readonly scope?: string;
   readonly score?: number;
   /** Tag values keyed by lowercased tag GROUP name (alias is resolved away). */
   readonly tags: Readonly<Record<string, string>>;

package/src/mindmap/parser.ts

@@ -243,7 +243,7 @@ export function parseMindmap(
         if (descResult.needsColon) {
           pushWarning(
             lineNumber,
-            `Use "description: ${descResult.text}" — colon is required.`
+            `Use "description: ${descResult.text}" — bare "description" is deprecated.`
           );
         }
         // Find parent node from indent stack

package/src/sitemap/parser.ts

@@ -486,7 +486,7 @@ export function parseSitemap(
         if (descResult.needsColon) {
           pushWarning(
             lineNumber,
-            `Use "description: ${descResult.text}" — colon is required.`
+            `Use "description: ${descResult.text}" — bare "description" is deprecated.`
           );
         }
         const parent = findParentNode(indent, indentStack);

package/src/utils/legend-d3.ts

@@ -198,6 +198,48 @@ function renderCapsule(
     .attr('font-family', FONT_FAMILY)
     .text(capsule.groupName);
 
+  // Continuous ramp (choropleth group): min | gradient | max, in place of dots.
+  if (capsule.gradient) {
+    const gr = capsule.gradient;
+    const gradId = `dgmo-legend-ramp-${capsule.groupName.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`;
+    const def = g.append('defs').append('linearGradient').attr('id', gradId);
+    def
+      .append('stop')
+      .attr('offset', '0%')
+      .attr('stop-color', mix(gr.hue, gr.base, 15));
+    def.append('stop').attr('offset', '100%').attr('stop-color', gr.hue);
+    g.append('text')
+      .attr('x', gr.minX)
+      .attr('y', gr.textY)
+      .attr('dominant-baseline', 'central')
+      .attr('font-size', LEGEND_ENTRY_FONT_SIZE)
+      .attr('fill', palette.textMuted)
+      .attr('pointer-events', 'none')
+      .attr('font-family', FONT_FAMILY)
+      .text(gr.minText);
+    // Class + raw min/max so the app can scrub the ramp (x → value) and
+    // highlight the regions whose score lands near the cursor.
+    g.append('rect')
+      .attr('class', 'dgmo-legend-gradient-ramp')
+      .attr('data-ramp-min', gr.min)
+      .attr('data-ramp-max', gr.max)
+      .attr('x', gr.rampX)
+      .attr('y', gr.rampY)
+      .attr('width', gr.rampW)
+      .attr('height', gr.rampH)
+      .attr('rx', 2)
+      .attr('fill', `url(#${gradId})`);
+    g.append('text')
+      .attr('x', gr.maxX)
+      .attr('y', gr.textY)
+      .attr('dominant-baseline', 'central')
+      .attr('font-size', LEGEND_ENTRY_FONT_SIZE)
+      .attr('fill', palette.textMuted)
+      .attr('pointer-events', 'none')
+      .attr('font-family', FONT_FAMILY)
+      .text(gr.maxText);
+  }
+
   // Entry dots + labels
   for (const entry of capsule.entries) {
     const entryG = g

package/src/utils/legend-layout.ts

@@ -20,7 +20,7 @@ import {
   truncateLegendText,
 } from './legend-constants';
 
-import type { LegendGroupData } from './legend-svg';
+import type { LegendGroupData } from './legend-types';
 import type {
   LegendConfig,
   LegendState,
@@ -41,6 +41,85 @@ const CONTROL_FONT_SIZE = 11;
 const CONTROL_ICON_GAP = 4;
 const CONTROL_GAP = 8;
 
+// Continuous-ramp swatch dims (choropleth groups) — match the legacy map ramp
+// block so the gradient reads the same now that it lives in the top legend.
+const RAMP_LEGEND_W = 80;
+const RAMP_LEGEND_H = 8;
+const RAMP_LABEL_GAP = 6;
+
+/** Compact numeric label for a ramp end (integers bare; else 1 decimal). */
+function fmtRamp(n: number): string {
+  return Number.isInteger(n) ? String(n) : String(Math.round(n * 10) / 10);
+}
+
+/** Width of a gradient group's capsule: pill + min label + ramp + max label. */
+function gradientCapsuleWidth(
+  name: string,
+  gradient: NonNullable<LegendGroupData['gradient']>
+): number {
+  const pw = pillWidth(name);
+  const minW = measureLegendText(fmtRamp(gradient.min), LEGEND_ENTRY_FONT_SIZE);
+  const maxW = measureLegendText(fmtRamp(gradient.max), LEGEND_ENTRY_FONT_SIZE);
+  return (
+    LEGEND_CAPSULE_PAD +
+    pw +
+    4 +
+    minW +
+    RAMP_LABEL_GAP +
+    RAMP_LEGEND_W +
+    RAMP_LABEL_GAP +
+    maxW +
+    LEGEND_CAPSULE_PAD
+  );
+}
+
+/** Active capsule for a continuous-ramp (choropleth) group. */
+function buildGradientCapsuleLayout(
+  group: LegendGroupData,
+  gradient: NonNullable<LegendGroupData['gradient']>
+): LegendCapsuleLayout {
+  const pw = pillWidth(group.name);
+  const minText = fmtRamp(gradient.min);
+  const maxText = fmtRamp(gradient.max);
+  const minW = measureLegendText(minText, LEGEND_ENTRY_FONT_SIZE);
+  const gx = LEGEND_CAPSULE_PAD + pw + 4;
+  const minX = gx;
+  const rampX = gx + minW + RAMP_LABEL_GAP;
+  const maxX = rampX + RAMP_LEGEND_W + RAMP_LABEL_GAP;
+  const width = gradientCapsuleWidth(group.name, gradient);
+  return {
+    groupName: group.name,
+    x: 0,
+    y: 0,
+    width,
+    height: LEGEND_HEIGHT,
+    pill: {
+      groupName: group.name,
+      x: LEGEND_CAPSULE_PAD,
+      y: LEGEND_CAPSULE_PAD,
+      width: pw,
+      height: LEGEND_HEIGHT - LEGEND_CAPSULE_PAD * 2,
+      isActive: true,
+    },
+    entries: [],
+    gradient: {
+      rampX,
+      rampY: (LEGEND_HEIGHT - RAMP_LEGEND_H) / 2,
+      rampW: RAMP_LEGEND_W,
+      rampH: RAMP_LEGEND_H,
+      min: gradient.min,
+      max: gradient.max,
+      minText,
+      minX,
+      maxText,
+      maxX,
+      textY: LEGEND_HEIGHT / 2,
+      hue: gradient.hue,
+      base: gradient.base,
+    },
+  };
+}
+
 // ── Measurement helpers ─────────────────────────────────────
 
 export function pillWidth(name: string): number {
@@ -267,7 +346,7 @@ export function computeLegendLayout(
 
   const visibleGroups = config.showEmptyGroups
     ? groups
-    : groups.filter((g) => g.entries.length > 0);
+    : groups.filter((g) => g.entries.length > 0 || !!g.gradient);
   if (
     visibleGroups.length === 0 &&
     (!configControls || configControls.length === 0) &&
@@ -364,7 +443,7 @@ export function computeLegendLayout(
         groupAvailW,
         config.capsulePillAddonWidth ?? 0
       );
-    } else if (!activeGroupName) {
+    } else if (!activeGroupName || config.showInactivePills) {
       const pw = pillWidth(g.name);
       pills.push({
         groupName: g.name,
@@ -413,6 +492,7 @@ function buildCapsuleLayout(
   containerWidth: number,
   addonWidth = 0
 ): LegendCapsuleLayout {
+  if (group.gradient) return buildGradientCapsuleLayout(group, group.gradient);
   const pw = pillWidth(group.name);
   const info = capsuleWidth(
     group.name,

package/src/utils/legend-svg.ts

@@ -18,6 +18,7 @@ import type {
   LegendPalette,
   LegendCapsuleLayout,
   LegendPillLayout,
+  LegendGroupData,
 } from './legend-types';
 import {
   LEGEND_HEIGHT,
@@ -31,14 +32,6 @@ import { FONT_FAMILY } from '../fonts';
 
 // ── Types ────────────────────────────────────────────────────
 
-export interface LegendGroupData {
-  readonly name: string;
-  readonly entries: ReadonlyArray<{
-    readonly value: string;
-    readonly color: string;
-  }>;
-}
-
 interface LegendRenderOptions {
   palette: { bg: string; surface: string; text: string; textMuted: string };
   isDark: boolean;

package/src/utils/legend-types.ts

@@ -73,10 +73,30 @@ export interface ControlsGroupConfig {
   toggles: ControlsGroupToggle[];
 }
 
+// ── Group Data ──────────────────────────────────────────────
+
+export interface LegendGroupData {
+  readonly name: string;
+  readonly entries: ReadonlyArray<{
+    readonly value: string;
+    readonly color: string;
+  }>;
+  /** Continuous (choropleth) groups carry a gradient ramp instead of discrete
+   *  entries — its active capsule renders `min ▭gradient▭ max` rather than dots.
+   *  Additive: only the map sets it; every other caller omits it and renders
+   *  unchanged. When set, `entries` is empty. */
+  readonly gradient?: {
+    readonly min: number;
+    readonly max: number;
+    readonly hue: string;
+    readonly base: string;
+  };
+}
+
 // ── Config ──────────────────────────────────────────────────
 
 export interface LegendConfig {
-  groups: readonly import('./legend-svg').LegendGroupData[];
+  groups: readonly LegendGroupData[];
   position: LegendPosition;
   controls?: LegendControl[];
   controlsGroup?: ControlsGroupConfig;
@@ -87,6 +107,11 @@ export interface LegendConfig {
   capsulePillAddonWidth?: number;
   /** When true, groups with no entries are still rendered as collapsed pills. Default: false (empty groups hidden). */
   showEmptyGroups?: boolean;
+  /** When true, INACTIVE sibling groups still render as collapsed pills next to
+   *  the active capsule (preview only — export still shows just the active
+   *  group). Lets the user click a sibling to switch the active group. Default
+   *  false (legacy: when one group is active the others are hidden). */
+  showInactivePills?: boolean;
 }
 
 export interface LegendPalette {
@@ -132,6 +157,24 @@ export interface LegendCapsuleLayout {
   moreCount?: number;
   /** X offset where addon content (e.g. eye icon) can be placed — after pill, before entries */
   addonX?: number;
+  /** Continuous-ramp swatch (choropleth groups) drawn in place of entry dots:
+   *  `minText` | gradient rect | `maxText`, all vertically centred. */
+  gradient?: {
+    rampX: number;
+    rampY: number;
+    rampW: number;
+    rampH: number;
+    /** Raw numeric ends (for the app's gradient-scrub: x → value). */
+    min: number;
+    max: number;
+    minText: string;
+    minX: number;
+    maxText: string;
+    maxX: number;
+    textY: number;
+    hue: string;
+    base: string;
+  };
 }
 
 export interface LegendControlLayout {