@diagrammo/dgmo 0.20.2 → 0.21.0

package/gallery/fixtures/map-choropleth.dgmo

@@ -1,10 +1,10 @@
 map US Sales by State
 region us-states
-metric Sales ($M)
+region-metric Sales ($M)
 
-California score: 92
-Texas score: 78
-New York score: 64
-Florida score: 51
-Washington score: 40
-Colorado score: 30
+California value: 92
+Texas value: 78
+New York value: 64
+Florida value: 51
+Washington value: 40
+Colorado value: 30

package/gallery/fixtures/map-pois.dgmo

@@ -1,9 +1,9 @@
 map Data Center Footprint
-size-metric Requests/s
+poi-metric Requests/s
 
-poi Denver as hub size: 90
-poi Dallas size: 320
-poi Seattle size: 180
+poi Denver as hub value: 90
+poi Dallas value: 320
+poi Seattle value: 180
 
 hub -> Dallas
 hub -> Seattle

package/gallery/fixtures/map-region-scope.dgmo

@@ -1,15 +1,15 @@
 map Region Scope Disambiguation
 region us-states
-metric Sales ($M)
+region-metric Sales ($M)
 region-labels abbrev
 subtitle Pin a country/state name clash by ISO code (US-GA) or name + scope (Georgia US)
 
-California score: 92
-Texas score: 78
+California value: 92
+Texas value: 78
 // "Georgia" clashes with the country GE — pin the state. Both lines are
 // equivalent; use whichever reads best:
-//   terse ISO code:  US-GA score: 64
-//   name + scope:    Georgia US score: 64
-US-GA score: 64
-Florida score: 51
-Washington score: 40
+//   terse ISO code:  US-GA value: 64
+//   name + scope:    Georgia US value: 64
+US-GA value: 64
+Florida value: 51
+Washington value: 40

package/gallery/fixtures/map-route.dgmo

@@ -1,9 +1,8 @@
 map Caribbean Cruise
 projection mercator
 
-route style: arc
-  Miami label: Embark
-  Havana
-  Kingston
-  Santo Domingo
-  Miami
+route Miami style: arc
+  -weigh anchor-> Havana
+  -> Kingston
+  -> Santo Domingo
+  -> Miami

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@diagrammo/dgmo",
-  "version": "0.20.2",
+  "version": "0.21.0",
   "description": "DGMO diagram markup language — parser, renderer, and color system",
   "license": "MIT",
   "repository": {

package/src/completion.ts

@@ -509,7 +509,7 @@ export const COMPLETION_REGISTRY = new Map<string, DirectiveSpec>([
   [
     'map',
     // Geographic map directives (§24B.2/.7). `poi`/`route` are content
-    // keywords, not directives; metadata keys (score/size/label) live in the
+    // keywords, not directives; metadata keys (value/label/style) live in the
     // reserved-key registry.
     withGlobals({
       region: {
@@ -521,9 +521,14 @@ export const COMPLETION_REGISTRY = new Map<string, DirectiveSpec>([
         description: 'Override the auto projection',
         values: ['equirectangular', 'natural-earth', 'albers-usa', 'mercator'],
       },
-      metric: { description: 'Label for the region score ramp' },
-      'size-metric': { description: 'Label for the POI size channel' },
-      scale: { description: 'Override score ramp anchors: scale <min> <max>' },
+      'region-metric': { description: 'Label for the region value ramp' },
+      'poi-metric': {
+        description: 'Label for the POI value (marker size) channel',
+      },
+      'flow-metric': {
+        description: 'Label for the edge/leg value (thickness) channel',
+      },
+      scale: { description: 'Override value ramp anchors: scale <min> <max>' },
       'region-labels': {
         description: 'Subdivision name labels',
         values: ['full', 'abbrev', 'off'],

package/src/editor/keywords.ts

@@ -153,13 +153,16 @@ export const DIRECTIVE_KEYWORDS = new Set([
   // Map (§24B) directives
   'region',
   'projection',
-  'metric',
-  'size-metric',
+  'region-metric',
+  'poi-metric',
+  'flow-metric',
   'region-labels',
   'poi-labels',
   'default-country',
   'default-state',
   'no-legend',
+  'muted',
+  'natural',
   'subtitle',
   'caption',
   'poi',

package/src/map/layout.ts

@@ -73,6 +73,21 @@ const RIVER_WIDTH = 1.3; // px stroke width for river lines
 // a clear gray rather than sinking into the dark background.
 const FOREIGN_TINT_LIGHT = 30;
 const FOREIGN_TINT_DARK = 62;
+// MUTED basemap — used when a colouring dimension (score ramp or a tag group) is
+// active. The data hues may themselves be blue or green (e.g. `Core blue`,
+// `Growth teal`), which collide with the decorative blue-water / green-land
+// dress: a blue region vanishes into the ocean, a green one into the land. So
+// when regions carry the data signal the basemap RECEDES to neutral grays —
+// water and unscored/neighbour land become low-saturation gray, leaving the data
+// fills as the only saturated thing on the map (the cartographic norm for a
+// choropleth). Plain reference maps with no data keep the blue/green dress.
+// Light land is left at the page bg (cleanest white ground for the data hues);
+// dark land lifts off the near-black surface so dark-mixed tints stay legible.
+const MUTED_WATER_LIGHT = 14; // % gray of bg — pale sea
+const MUTED_WATER_DARK = 10;
+const MUTED_FOREIGN_LIGHT = 28; // neighbour land — grayer than the sea
+const MUTED_FOREIGN_DARK = 16;
+const MUTED_LAND_DARK = 24; // subject land on dark (light land = palette.bg)
 const COLO_R = 9; // spiderfy radius
 const GOLDEN_ANGLE = 2.399963229728653; // rad (137.5deg) -- even spiral, no random
 const FAN_STEP = 16; // px perpendicular offset between parallel edges
@@ -86,9 +101,9 @@ export interface MapLayoutRegion {
   readonly label?: string;
   readonly lineNumber: number;
   readonly layer: 'base' | 'country' | 'us-state';
-  /** The region's score (if any) — emitted as `data-score` so the app can
+  /** The region's value (if any) — emitted as `data-value` so the app can
    *  highlight by gradient-scrub proximity. */
-  readonly score?: number;
+  readonly value?: number;
   /** The region's tag values keyed by group (lowercased) — emitted as
    *  `data-tag-<group>` so the app can highlight on legend-entry hover. */
   readonly tags?: Readonly<Record<string, string>>;
@@ -119,6 +134,9 @@ export interface MapLayoutPoi {
   readonly implicit: boolean;
   readonly isOrigin: boolean; // route origin -> distinct marker
   readonly routeNumber?: number; // route stop badge
+  /** Tag values keyed by lowercased group name — emitted as `data-tag-<group>`
+   *  so the app can spotlight markers on legend-entry hover (mirrors regions). */
+  readonly tags?: Readonly<Record<string, string>>;
 }
 
 /** A drawn connector -- an edge or a route leg (same geometry contract). */
@@ -276,19 +294,37 @@ const US_NON_CONUS = new Set([
 
 /** The map's water / backdrop colour for a palette — the single source of truth
  *  shared by the renderer's `<rect>` fill and any host wrapper that needs to
- *  match it (so letterbox gaps around the SVG don't show a stray band). */
-export function mapBackgroundColor(palette: PaletteColors): string {
+ *  match it (so letterbox gaps around the SVG don't show a stray band). When
+ *  `dataActive` (a score ramp or tag group is colouring regions) the sea recedes
+ *  to a pale neutral so blue/green data hues don't blend into it. */
+export function mapBackgroundColor(
+  palette: PaletteColors,
+  isDark = false,
+  dataActive = false
+): string {
+  if (dataActive)
+    return mix(
+      palette.colors.gray,
+      palette.bg,
+      isDark ? MUTED_WATER_DARK : MUTED_WATER_LIGHT
+    );
   return mix(palette.colors.blue, palette.bg, WATER_TINT);
 }
 
-/** The map's neutral (unscored/untagged) LAND colour — the green base every
- *  region blends from. Exported so a host can DIM a region to plain land
- *  (rather than lowering opacity, which would let the blue water show through
- *  and make the shape read as ocean). Matches the layout's `neutralFill`. */
+/** The map's neutral (unscored/untagged) LAND colour — the base every region
+ *  blends from. Exported so a host can DIM a region to plain land (rather than
+ *  lowering opacity, which would let the water show through and make the shape
+ *  read as ocean). Matches the layout's `neutralFill`. Green reference dress by
+ *  default; neutral (page bg on light, lifted gray on dark) when `dataActive`. */
 export function mapNeutralLandColor(
   palette: PaletteColors,
-  isDark: boolean
+  isDark: boolean,
+  dataActive = false
 ): string {
+  if (dataActive)
+    return isDark
+      ? mix(palette.colors.gray, palette.bg, MUTED_LAND_DARK)
+      : palette.bg;
   return mix(
     palette.colors.green,
     palette.bg,
@@ -344,21 +380,9 @@ export function layoutMap(
   }
   const usLayer = wantsUsStates ? decodeLayer(data.usStates) : null;
 
-  // Land is a muted green; the ocean/backdrop is blue. Scored/tagged regions
-  // paint over the land base, and the score ramp blends FROM the land colour so
-  // low scores stay land-toned rather than fading out. In a US view the world
-  // layer is just neighbour context (Mexico/Canada at the frame edge) — fill it
-  // gray so the green US reads as the subject; world maps (no us-states layer)
-  // keep green land for every country.
-  const landTint = isDark ? LAND_TINT_DARK : LAND_TINT_LIGHT;
-  const neutralFill = mix(palette.colors.green, palette.bg, landTint);
-  const water = mapBackgroundColor(palette);
   const usContext = usLayer !== null;
-  const foreignFill = mix(
-    palette.colors.gray,
-    palette.bg,
-    isDark ? FOREIGN_TINT_DARK : FOREIGN_TINT_LIGHT
-  );
+  // Basemap fills (`water` / `neutralFill` / `foreignFill`) depend on whether a
+  // colouring dimension is active — defined below, once `activeGroup` is known.
   // Region borders: a clearly dark outline in BOTH themes. palette.text flips
   // (dark on light, light on dark), so mix toward whichever of text/bg is the
   // dark one — never a light hairline over the land fills.
@@ -367,29 +391,30 @@ export function layoutMap(
     : mix(palette.text, palette.bg, 78); // light theme: near-text dark outline
 
   // -- Region fill model (choropleth + categorical; AR4/AR6) --
-  const scores = resolved.regions
-    .filter((r) => r.score !== undefined)
-    .map((r) => r.score!);
+  const values = resolved.regions
+    .filter((r) => r.value !== undefined)
+    .map((r) => r.value!);
   const scaleOverride = resolved.directives.scale;
-  const rampMin = scaleOverride ? scaleOverride.min : Math.min(...scores);
-  const rampMax = scaleOverride ? scaleOverride.max : Math.max(...scores);
-  // Score ramp is red so scored regions stand out against the blue water
+  const rampMin = scaleOverride ? scaleOverride.min : Math.min(...values);
+  const rampMax = scaleOverride ? scaleOverride.max : Math.max(...values);
+  // Value ramp is red so valued regions stand out against the blue water
   // (palette.primary is a blue in most palettes and would blend in).
   const rampHue = palette.colors.red;
-  const hasRamp = scores.length > 0;
+  const hasRamp = values.length > 0;
 
-  // Colouring dimension (AR4, bivariate): the score ramp and each tag group are
-  // mutually-exclusive selectable groups. `SCORE_NAME` is the ramp's group name
-  // (the metric label, or "Score"); the reserved token `score` also selects it.
-  // Exactly one dimension is active and drives every region's fill.
-  const SCORE_NAME = hasRamp
-    ? resolved.directives.metric?.trim() || 'Score'
+  // Colouring dimension (AR4, bivariate): the value ramp and each tag group are
+  // mutually-exclusive selectable groups. `VALUE_NAME` is the ramp's group name
+  // (the region-metric label, or "Value"). Exactly one dimension is active and
+  // drives every region's fill. The value ramp is the default-active dimension
+  // whenever any region has a value (the old `active-tag score` token is gone —
+  // there is nothing to force; selecting a tag group is what `active-tag` does).
+  const VALUE_NAME = hasRamp
+    ? resolved.directives.regionMetric?.trim() || 'Value'
     : null;
   const matchColorGroup = (v: string): string | null => {
     const lv = v.trim().toLowerCase();
     if (lv === 'none') return null;
-    if (SCORE_NAME && (lv === 'score' || lv === SCORE_NAME.toLowerCase()))
-      return SCORE_NAME;
+    if (lv === VALUE_NAME?.toLowerCase()) return VALUE_NAME;
     const tg = resolved.tagGroups.find((g) => g.name.toLowerCase() === lv);
     return tg ? tg.name : v; // unknown name passes through → renders neutral
   };
@@ -400,13 +425,41 @@ export function layoutMap(
   } else if (resolved.directives.activeTag !== undefined) {
     activeGroup = matchColorGroup(resolved.directives.activeTag);
   } else {
-    // Default: colour by score when scores exist (preserves the historical
-    // "score wins" default), else the first declared tag group.
+    // Default: colour by the value ramp when values exist, else the first
+    // declared tag group.
     activeGroup =
-      SCORE_NAME ??
+      VALUE_NAME ??
       (resolved.tagGroups.length > 0 ? resolved.tagGroups[0]!.name : null);
   }
-  const activeIsScore = SCORE_NAME !== null && activeGroup === SCORE_NAME;
+  const activeIsScore = VALUE_NAME !== null && activeGroup === VALUE_NAME;
+
+  // Basemap dress. When a colouring dimension is active the regions carry the
+  // signal, so the sea/land recede to neutral grays (the data hues — which may be
+  // blue or green — would otherwise blend into a blue ocean / green land). A
+  // plain reference map (no score, no tag → activeGroup null) keeps the blue
+  // water + green land. The bare `muted` / `natural` flags force either dress
+  // regardless (so two maps in a deck can match); absent → this auto rule. In a
+  // US view the surrounding world layer is always recessive gray so the US reads
+  // as the subject.
+  const mutedBasemap =
+    resolved.directives.basemapStyle === 'muted'
+      ? true
+      : resolved.directives.basemapStyle === 'natural'
+        ? false
+        : activeGroup !== null;
+  const neutralFill = mapNeutralLandColor(palette, isDark, mutedBasemap);
+  const water = mapBackgroundColor(palette, isDark, mutedBasemap);
+  const foreignFill = mix(
+    palette.colors.gray,
+    palette.bg,
+    mutedBasemap
+      ? isDark
+        ? MUTED_FOREIGN_DARK
+        : MUTED_FOREIGN_LIGHT
+      : isDark
+        ? FOREIGN_TINT_DARK
+        : FOREIGN_TINT_LIGHT
+  );
 
   // Score ramp base: a NEUTRAL tint of the page, NOT the (green) land colour —
   // blending red toward green produced muddy brown mid-tones that blurred into
@@ -415,7 +468,7 @@ export function layoutMap(
   // off the near-black surface so the lowest scores read as a clear muted red
   // rather than sinking to maroon-black.
   const rampBase = isDark ? mix(palette.surface, palette.text, 28) : palette.bg;
-  const fillForScore = (s: number): string => {
+  const fillForValue = (s: number): string => {
     const t = rampMax > rampMin ? (s - rampMin) / (rampMax - rampMin) : 1;
     const pct = RAMP_FLOOR + Math.max(0, Math.min(1, t)) * (100 - RAMP_FLOOR);
     return mix(rampHue, rampBase, pct);
@@ -451,14 +504,14 @@ export function layoutMap(
   };
 
   /** A region's fill under the ACTIVE colouring dimension (AR4, bivariate):
-   *  score-active → ramp for scored regions, neutral otherwise; a tag group
-   *  active → that group's tag colour, neutral otherwise (score ignored). */
+   *  value-active → ramp for valued regions, neutral otherwise; a tag group
+   *  active → that group's tag colour, neutral otherwise (value ignored). */
   const regionFill = (r: {
-    score?: number;
+    value?: number;
     tags: Readonly<Record<string, string>>;
   }): string => {
     if (activeIsScore) {
-      return r.score !== undefined ? fillForScore(r.score) : neutralFill;
+      return r.value !== undefined ? fillForValue(r.value) : neutralFill;
     }
     return tagFill(r.tags, activeGroup) ?? neutralFill;
   };
@@ -778,7 +831,7 @@ export function layoutMap(
         stroke: regionStroke,
         lineNumber,
         layer: 'us-state',
-        ...(r?.score !== undefined && { score: r.score }),
+        ...(r?.value !== undefined && { value: r.value }),
         ...(r && Object.keys(r.tags).length > 0 && { tags: r.tags }),
       });
       const ctr = geoPath(proj).centroid(f as never);
@@ -976,6 +1029,13 @@ export function layoutMap(
       // redundant US country polygon underneath it (it only adds a coarser base
       // and a doubled outline).
       if (layerKind === 'country' && usContext && iso === 'US') continue;
+      // Antarctica is omitted from the world basemap. The natural-earth world
+      // frame is clamped to ~-58°N and global views take the stretch path (no
+      // clipExtent), so AQ's -90° geometry projects below the frame and spills
+      // out the bottom of the canvas as a distorted strip. Data world maps omit
+      // Antarctica by convention anyway. Keep it only if explicitly referenced.
+      if (layerKind === 'country' && iso === 'AQ' && !regionById.has('AQ'))
+        continue;
       const r = regionById.get(iso);
       // Cull off-view land in a regional view; in a global view keep all land
       // but still drop antimeridian frame-fillers (Fiji et al.).
@@ -1005,7 +1065,7 @@ export function layoutMap(
         lineNumber,
         layer,
         ...(label !== undefined && { label }),
-        ...(isThisLayer && r.score !== undefined && { score: r.score }),
+        ...(isThisLayer && r.value !== undefined && { value: r.value }),
         ...(isThisLayer && Object.keys(r.tags).length > 0 && { tags: r.tags }),
       });
     }
@@ -1060,14 +1120,14 @@ export function layoutMap(
     }
   }
 
-  // -- POIs: project, size-scale, co-located spiderfy --
+  // -- POIs: project, value→size-scale, co-located spiderfy --
   const sizeVals = resolved.pois
-    .map((p) => Number(p.meta['size']))
+    .map((p) => Number(p.meta['value']))
     .filter((n) => Number.isFinite(n) && n > 0);
   const sizeMin = sizeVals.length ? Math.min(...sizeVals) : 0;
   const sizeMax = sizeVals.length ? Math.max(...sizeVals) : 0;
   const radiusFor = (p: ResolvedPoi): number => {
-    const v = Number(p.meta['size']);
+    const v = Number(p.meta['value']);
     if (!Number.isFinite(v) || v <= 0 || sizeMax <= 0) return R_DEFAULT;
     // sqrt so AREA encodes the value
     const t =
@@ -1153,6 +1213,7 @@ export function layoutMap(
         implicit: !!e.p.implicit,
         isOrigin: originIds.has(e.p.id),
         ...(num !== undefined && { routeNumber: num }),
+        ...(Object.keys(e.p.tags).length > 0 && { tags: e.p.tags }),
       });
     });
   }
@@ -1201,31 +1262,50 @@ export function layoutMap(
     return `M${ax},${ay}Q${px},${py} ${bx},${by}`;
   };
 
-  // Routes: legs between consecutive stops (loop closing leg included).
+  // Routes: each leg is an edge (fromId → toId) carrying its own label,
+  // value→thickness, and arc shape. Loop-closing legs are explicit in `rt.legs`;
+  // the origin is never double-marked because `stopIds` is unique.
+  const routeLegVals = resolved.routes
+    .flatMap((rt) => rt.legs)
+    .map((l) => Number(l.value))
+    .filter((n) => Number.isFinite(n) && n > 0);
+  const rlMin = routeLegVals.length ? Math.min(...routeLegVals) : 0;
+  const rlMax = routeLegVals.length ? Math.max(...routeLegVals) : 0;
+  const routeWidthFor = (v: number): number => {
+    if (!Number.isFinite(v) || v <= 0 || rlMax <= 0) return W_MIN;
+    const t = rlMax > rlMin ? (v - rlMin) / (rlMax - rlMin) : 1;
+    return W_MIN + t * (W_MAX - W_MIN);
+  };
   for (const rt of resolved.routes) {
-    const curved = rt.meta['style'] === 'arc';
-    for (let i = 1; i < rt.stopIds.length; i++) {
-      const a = poiScreen.get(rt.stopIds[i - 1]!);
-      const b = poiScreen.get(rt.stopIds[i]!);
+    for (const leg of rt.legs) {
+      const a = poiScreen.get(leg.fromId);
+      const b = poiScreen.get(leg.toId);
       if (!a || !b) continue;
+      const mx = (a.cx + b.cx) / 2;
+      const my = (a.cy + b.cy) / 2;
       legs.push({
-        d: legPath(a, b, curved, 0),
-        width: W_MIN,
+        d: legPath(a, b, leg.style === 'arc', 0),
+        width: routeWidthFor(Number(leg.value)),
         color: mix(palette.text, palette.bg, 72),
         arrow: true,
-        lineNumber: rt.lineNumber,
+        lineNumber: leg.lineNumber,
+        ...(leg.label !== undefined && {
+          label: leg.label,
+          labelX: mx,
+          labelY: my - 4,
+        }),
       });
     }
   }
 
   // Edges: group by unordered endpoint pair for deterministic fan-out (AR9).
   const weightVals = resolved.edges
-    .map((e) => Number(e.meta['weight']))
+    .map((e) => Number(e.meta['value']))
     .filter((n) => Number.isFinite(n) && n > 0);
   const wMin = weightVals.length ? Math.min(...weightVals) : 0;
   const wMax = weightVals.length ? Math.max(...weightVals) : 0;
   const widthFor = (e: ResolvedEdge): number => {
-    const v = Number(e.meta['weight']);
+    const v = Number(e.meta['value']);
     if (!Number.isFinite(v) || v <= 0 || wMax <= 0) return W_MIN;
     const t = wMax > wMin ? (v - wMin) / (wMax - wMin) : 1;
     return W_MIN + t * (W_MAX - W_MIN);
@@ -1559,17 +1639,18 @@ export function layoutMap(
       name: g.name,
       entries: g.entries.map((e) => ({ value: e.value, color: e.color })),
     }));
-    // Only the colouring dimensions (score ramp + tag groups) get a legend.
-    // POI size and edge weight are self-evident from the marker/line scale and
-    // intentionally carry no key.
+    // Only the colouring dimensions (value ramp + tag groups) get a legend.
+    // POI size and edge thickness are self-evident from the marker/line scale and
+    // intentionally carry no key (the poi-metric/flow-metric labels are captured
+    // for future use but not rendered as legend keys in v1).
     if (tagGroups.length > 0 || hasRamp) {
       legend = {
         tagGroups,
         activeGroup,
         ...(hasRamp && {
           ramp: {
-            ...(resolved.directives.metric !== undefined && {
-              metric: resolved.directives.metric,
+            ...(resolved.directives.regionMetric !== undefined && {
+              metric: resolved.directives.regionMetric,
             }),
             min: rampMin,
             max: rampMax,