@diagrammo/dgmo 0.25.5 → 0.27.0

package/src/map/renderer.ts

@@ -12,6 +12,7 @@ import {
   TITLE_Y,
 } from '../utils/title-constants';
 import { mix } from '../palettes/color-utils';
+import { measureText } from '../utils/text-measure';
 import { renderLegendD3 } from '../utils/legend-d3';
 import type { LegendConfig, LegendState } from '../utils/legend-types';
 import { mapLegendConfig, mapLegendGroups } from './legend-band';
@@ -185,22 +186,32 @@ function coastlineOuterRings(
  *  the accepted cross-region overdraw artifact behave exactly as before. */
 function appendWaterLines(
   g: Sel,
+  defs: Sel,
+  coastId: string,
   outerRings: readonly string[],
   style: MapLayoutCoastlineStyle,
   flatWater: string
 ): void {
   const d = outerRings.join(' ');
+  if (!d) return;
+  // The coast geometry is byte-for-byte identical across every line-level and
+  // both passes (only stroke colour/width differ). On a world map that compound
+  // path is ~200KB, so emitting it ~12× inline ballooned the SVG to multi-MB and
+  // overflowed the SSG HTML reparse. Define it once and `<use>` it: same pixels,
+  // a fraction of the bytes.
+  defs.append('path').attr('id', coastId).attr('d', d).attr('fill', 'none');
+  const ref = `#${coastId}`;
   const linesOuterFirst = [...style.lines].sort((a, b) => b.d - a.d);
   for (const line of linesOuterFirst) {
-    g.append('path')
-      .attr('d', d)
+    g.append('use')
+      .attr('href', ref)
       .attr('stroke', style.color)
       .attr('stroke-width', 2 * (line.d + line.thickness))
       .attr('stroke-opacity', line.opacity)
       .attr('stroke-linejoin', 'round')
       .attr('stroke-linecap', 'round');
-    g.append('path')
-      .attr('d', d)
+    g.append('use')
+      .attr('href', ref)
       .attr('stroke', flatWater)
       .attr('stroke-width', 2 * line.d)
       .attr('stroke-linejoin', 'round')
@@ -460,6 +471,8 @@ export function renderMap(
       .attr('mask', `url(#${maskId})`);
     appendWaterLines(
       gWater,
+      defs,
+      'dgmo-map-coast',
       // Pass the canvas frame so edges collinear with it (the antimeridian on a
       // world map, regional clipExtent cuts) don't get ringed as fake coast —
       // land runs cleanly to the render-area edge.
@@ -513,6 +526,193 @@ export function renderMap(
     }
   }
 
+  // ── City dots — a faint gazetteer scatter for geographic orientation, over
+  // the basemap but under connectors/POIs/labels. Decorative (no pointer events,
+  // no data attributes); muted ink at low opacity so it reads as texture, not
+  // data. Suppressed entirely by the `no-cities` directive (empty array). ──
+  if (layout.cityDots.length) {
+    const gCities = svg
+      .append('g')
+      .attr('class', 'dgmo-map-cities')
+      .attr('fill', palette.textMuted)
+      .attr('fill-opacity', 0.28)
+      .style('pointer-events', 'none');
+    for (const c of layout.cityDots) {
+      gCities.append('circle').attr('cx', c.cx).attr('cy', c.cy).attr('r', c.r);
+    }
+  }
+
+  // ── Label clarity patch — repaint the clean region FILL under each POI label
+  // so the basemap line work beneath it (region borders, relief hachure, coast +
+  // river lines) dissolves where it would clutter the text. Crucially this is NOT
+  // a halo: the patch IS the same fill that already surrounds the label, so over
+  // plain land it is invisible and ONLY the crossing lines disappear — no white
+  // pad over flat colour. A blurred-blob mask feathers each patch into the map
+  // (soft edges, no hard rectangle). Sits above all basemap line work, below the
+  // dots / legs / labels. POI labels only; context/water labels keep their lines
+  // (they read as cartographic texture, not clutter).
+  //
+  // Collapsed cluster members are HIDDEN at rest, so their labels aren't on screen
+  // — patching under them would fade the basemap beneath an invisible label. So
+  // each cluster's member patches go in a per-cluster group tagged
+  // `data-cluster-deco`, which the app's spiderfy controller toggles in lockstep
+  // with the legs / member dots: the fade only appears once the fan is expanded.
+  // Non-clustered POI labels (and ALL labels in export / `no-cluster-pois`, where
+  // the fan is permanently open) keep the always-on patch so the static image
+  // matches what's on screen.
+  const clusterUi = !exportDims && !resolved.directives.noClusterPois;
+  const poiLabels = layout.labels.filter(
+    (l) => l.poiId !== undefined && !l.hidden
+  );
+  if (poiLabels.length) {
+    const patchBlurId = 'dgmo-map-label-patch-blur';
+    // Soft falloff so the patch dissolves into the surrounding basemap instead of
+    // ending on a hard edge. Tuned at the 11px label font. One shared filter for
+    // every patch group.
+    defs
+      .append('filter')
+      .attr('id', patchBlurId)
+      .attr('x', '-50%')
+      .attr('y', '-50%')
+      .attr('width', '200%')
+      .attr('height', '200%')
+      .append('feGaussianBlur')
+      .attr('in', 'SourceGraphic')
+      .attr('stdDeviation', 2.5);
+    const PAD = 8; // ≳ blur reach so culled regions can't lose a fringe
+
+    // Build one patch (mask of blurred blobs + the region fills they cross) for a
+    // set of labels. `decoCluster` tags the group so the app toggles it with the
+    // rest of the cluster's spiderfy decoration.
+    const buildPatch = (
+      labels: typeof poiLabels,
+      maskId: string,
+      decoCluster?: string
+    ): void => {
+      if (!labels.length) return;
+      const patchMask = defs
+        .append('mask')
+        .attr('id', maskId)
+        // userSpaceOnUse: the patch group's bbox is the whole basemap, but keep
+        // the mask region pinned to the canvas (parity with the water masks).
+        .attr('maskUnits', 'userSpaceOnUse')
+        .attr('x', 0)
+        .attr('y', 0)
+        .attr('width', width)
+        .attr('height', height);
+      // White blobs = where the patch shows; the surrounding black hides it. Each
+      // blob is a SOLID rounded rect sized to the text bbox so the core fully
+      // hides the line work behind the glyphs; the blur only feathers the outer
+      // edge. Solid core → if an engine drops the in-mask blur (some WebKit
+      // builds), it degrades to a clean stadium patch, never a halo.
+      const blobs = patchMask
+        .append('g')
+        .attr('filter', `url(#${patchBlurId})`);
+      // Padded rects (incl. the blur reach) drive both the mask AND the region
+      // cull below, so the two never disagree.
+      const blobRects: Array<{
+        x0: number;
+        y0: number;
+        x1: number;
+        y1: number;
+      }> = [];
+      for (const l of labels) {
+        const multi = l.lines && l.lines.length > 1;
+        const tw = multi
+          ? Math.max(...l.lines!.map((s) => measureText(s, LABEL_FONT)))
+          : measureText(l.text, LABEL_FONT);
+        const th = multi ? l.lines!.length * (LABEL_FONT + 2) : LABEL_FONT;
+        // Anchor → blob centre x; cy nudged up from the text baseline to the
+        // glyph visual centre.
+        const cx =
+          l.anchor === 'start'
+            ? l.x + tw / 2
+            : l.anchor === 'end'
+              ? l.x - tw / 2
+              : l.x;
+        const cy = l.y - LABEL_FONT * 0.3;
+        const w = tw + 8;
+        const h = th + 6;
+        blobs
+          .append('rect')
+          .attr('x', cx - w / 2)
+          .attr('y', cy - h / 2)
+          .attr('width', w)
+          .attr('height', h)
+          .attr('rx', h / 2)
+          .attr('fill', 'white');
+        blobRects.push({
+          x0: cx - w / 2 - PAD,
+          y0: cy - h / 2 - PAD,
+          x1: cx + w / 2 + PAD,
+          y1: cy + h / 2 + PAD,
+        });
+      }
+      const gPatch = svg
+        .append('g')
+        .attr('class', 'dgmo-map-label-patch')
+        .attr('mask', `url(#${maskId})`)
+        // Decorative cover — never a pointer target so region hover / name-on-
+        // hover reaches the real region paths beneath (WebKit hit-tests masked
+        // content).
+        .style('pointer-events', 'none');
+      // Per-cluster patch: tag as cluster decoration so the spiderfy controller
+      // shows/hides it in step with the fan. (The app collapses all `[data-
+      // cluster-deco]` to opacity 0 at rest, pre-paint, so there's no flash.)
+      if (decoCluster !== undefined)
+        gPatch.attr('data-cluster-deco', decoCluster);
+      // Redraw fills only (no stroke), in document order, but ONLY for regions
+      // whose bbox overlaps a label blob — the mask already hides everything
+      // else, so emitting the rest is pure SVG weight (matters on dense world
+      // maps). The kept regions reproduce the exact composite colour under each
+      // label, so the patch is seamless and the only visible change is the
+      // vanished line work.
+      for (const r of layout.regions) {
+        let minX = Infinity,
+          minY = Infinity,
+          maxX = -Infinity,
+          maxY = -Infinity;
+        for (const ring of parsePathRings(r.d))
+          for (const [px, py] of ring) {
+            if (px < minX) minX = px;
+            if (px > maxX) maxX = px;
+            if (py < minY) minY = py;
+            if (py > maxY) maxY = py;
+          }
+        const hit = blobRects.some(
+          (b) => minX <= b.x1 && maxX >= b.x0 && minY <= b.y1 && maxY >= b.y0
+        );
+        if (hit) gPatch.append('path').attr('d', r.d).attr('fill', r.fill);
+      }
+    };
+
+    if (clusterUi) {
+      // Always-on patch for labels that are visible at rest (non-cluster members).
+      buildPatch(
+        poiLabels.filter((l) => l.clusterMember === undefined),
+        'dgmo-map-label-patch'
+      );
+      // Per-cluster patches, hidden until the fan expands.
+      const byCluster = new Map<string, typeof poiLabels>();
+      for (const l of poiLabels) {
+        if (l.clusterMember === undefined) continue;
+        const arr = byCluster.get(l.clusterMember);
+        if (arr) arr.push(l);
+        else byCluster.set(l.clusterMember, [l]);
+      }
+      // Safe mask id from the iteration index — cluster ids can be coord-based
+      // (`@lat,lon`) and aren't `url(#…)`-safe; the raw id rides on the
+      // data-cluster-deco attribute instead.
+      let ci = 0;
+      for (const [cid, labs] of byCluster)
+        buildPatch(labs, `dgmo-map-label-patch-c${ci++}`, cid);
+    } else {
+      // Export / `no-cluster-pois`: fan is permanently open → one always-on patch
+      // over every POI label.
+      buildPatch(poiLabels, 'dgmo-map-label-patch');
+    }
+  }
+
   // ── AK / HI insets (albers-usa) — drawn in the FOREGROUND so the opaque ocean
   // box hides the main-map neighbour land (Mexico's Baja) behind it; the state
   // then draws on top, framed by the box border. ──
@@ -560,11 +760,23 @@ export function renderMap(
         .attr('y', 0)
         .attr('width', width)
         .attr('height', height);
+      // White reveal = the box interior, but eroded inward by `reach` (a black
+      // border stroke) so the seaward rings fade out before the frame instead of
+      // being hard-clipped at it — clipped ring fragments otherwise read as
+      // artifacts bumping into the crisp 1px border. Mirrors the main-map moat,
+      // applied inward.
+      const reach = Math.max(0, ...cs.lines.map((l) => l.d + l.thickness));
       for (const box of layout.insets) {
         const d =
           box.points.map((p, i) => `${i ? 'L' : 'M'}${p[0]},${p[1]}`).join('') +
           'Z';
-        mask.append('path').attr('d', d).attr('fill', 'white');
+        mask
+          .append('path')
+          .attr('d', d)
+          .attr('fill', 'white')
+          .attr('stroke', 'black')
+          .attr('stroke-width', 2 * reach)
+          .attr('stroke-linejoin', 'round');
       }
       // Neighbour land masks as land too — clipped to its box so it can't darken
       // an adjacent inset — keeping the AK/Canada land border free of rings.
@@ -607,6 +819,8 @@ export function renderMap(
         .attr('mask', `url(#${maskId})`);
       appendWaterLines(
         gInsetWater,
+        defs,
+        'dgmo-map-inset-coast',
         coastlineOuterRings(layout.insetRegions, cs.minExtent),
         cs,
         layout.background
@@ -620,6 +834,25 @@ export function renderMap(
           .attr('stroke-width', 0.5)
           .attr('stroke-linejoin', 'round');
     }
+
+    // Re-stroke each inset frame ON TOP (stroke-only, no fill) as the final
+    // inset layer — the early border path sits under the contextLand fill,
+    // region fills, and water-lines, so its inner half gets covered near the
+    // top/right edges and the frame reads as thin/fuzzy. This overlay keeps a
+    // crisp full-width border on every side.
+    for (const box of layout.insets) {
+      const d =
+        box.points.map((p, i) => `${i ? 'L' : 'M'}${p[0]},${p[1]}`).join('') +
+        'Z';
+      insetG
+        .append('path')
+        .attr('d', d)
+        .attr('fill', 'none')
+        .attr('stroke', mix(palette.text, palette.bg, 55))
+        .attr('stroke-width', 1)
+        .attr('stroke-linejoin', 'round')
+        .style('pointer-events', 'none');
+    }
   }
 
   // Code↔diagram sync: tag a synced element with its 1-based source line and,
@@ -647,7 +880,17 @@ export function renderMap(
       .attr('d', leg.d)
       .attr('stroke', leg.color)
       .attr('stroke-width', leg.width)
-      .attr('stroke-linecap', 'round');
+      .attr('stroke-linecap', 'round')
+      // Endpoint POI ids so a focused leg can co-highlight its two POIs (§17 sync).
+      .attr('data-from-id', leg.fromId)
+      .attr('data-to-id', leg.toId);
+    // Tag the line per tag value (lowercased, matching the legend-entry attrs) so
+    // a legend hover spotlights only the matching lines (§24B.6) — mirrors POIs.
+    if (leg.tags) {
+      for (const [group, value] of Object.entries(leg.tags)) {
+        p.attr(`data-tag-${group.toLowerCase()}`, value.toLowerCase());
+      }
+    }
     // A 0-width invisible leg path is hard to hit; pointer-events on the visible
     // stroke is enough for the line widths legs use.
     wireSync(p, leg.lineNumber);
@@ -698,7 +941,6 @@ export function renderMap(
   // the legs/hub/members visible but emit NO hit-area + NO badge, so there is
   // nothing for the app's spiderfy controller to collapse — the map reads the
   // same on screen as on paper.
-  const clusterUi = !exportDims && !resolved.directives.noClusterPois;
   const gSpider = svg.append('g').attr('class', 'dgmo-map-spider');
   for (const cl of layout.clusters) {
     // Pointer hit-area — bottom of the stack so member dots still take their own
@@ -755,6 +997,7 @@ export function renderMap(
       .attr('cy', poi.cy)
       .attr('r', poi.r)
       .attr('fill', poi.fill)
+      .attr('fill-opacity', poi.fillOpacity)
       .attr('stroke', poi.stroke)
       .attr('stroke-width', 1)
       .attr('data-line-number', poi.lineNumber)
@@ -807,7 +1050,7 @@ export function renderMap(
         lab.color,
         lab.haloColor,
         lab.halo,
-        LABEL_FONT,
+        lab.fontSize ?? LABEL_FONT,
         lab.italic,
         lab.letterSpacing
       )
@@ -836,6 +1079,18 @@ export function renderMap(
         line.attr('data-cluster-member', lab.clusterMember);
       wireSync(line, lab.lineNumber);
     }
+    // Region callout anchor dot: a small disc at the (too-small) region's true
+    // centroid, in the region's fill, so the leader visibly originates on the map.
+    if (lab.calloutDot) {
+      gLabels
+        .append('circle')
+        .attr('cx', lab.calloutDot.x)
+        .attr('cy', lab.calloutDot.y)
+        .attr('r', 2.5)
+        .attr('fill', lab.calloutDot.color)
+        .attr('stroke', mix(palette.text, palette.bg, 55))
+        .attr('stroke-width', 0.75);
+    }
     const t = emitText(
       gLabels,
       lab.x,
@@ -845,10 +1100,11 @@ export function renderMap(
       lab.color,
       lab.haloColor,
       lab.halo,
-      LABEL_FONT,
+      lab.fontSize ?? LABEL_FONT,
       lab.italic,
       lab.letterSpacing,
-      lab.lines
+      lab.lines,
+      lab.valueLine
     );
     // POI labels are spotlightable: tag with the POI id and make the text the
     // hover target (the app dims the other dots/labels on enter).
@@ -955,7 +1211,7 @@ export function renderMap(
   // ── Title / subtitle / caption (foreground — drawn last so they sit above the
   // basemap, POIs, and labels; layout reserves top padding so POIs clear them) ──
   // Soft bg halo so the banner stays legible over busy land/water (the muted
-  // subtitle/caption otherwise wash out on mid-toned palettes like gruvbox).
+  // subtitle/caption otherwise wash out on mid-toned palettes like nord).
   if (layout.title) {
     svg
       .append('text')
@@ -1032,7 +1288,8 @@ function emitText(
   fontSize: number,
   italic?: boolean,
   letterSpacing?: number,
-  lines?: readonly string[]
+  lines?: readonly string[],
+  valueLine?: string
 ): d3Selection.Selection<SVGTextElement, unknown, null, undefined> {
   const t = g
     .append('text')
@@ -1053,6 +1310,21 @@ function emitText(
         .attr('dy', i === 0 ? startDy : lineHeight)
         .text(ln);
     });
+  } else if (valueLine !== undefined) {
+    // A choropleth region's name over its metric value: name on top, value below
+    // in a smaller, dimmer line (same fill, reduced opacity). Raise the block so
+    // its centre sits on the placement `y`. The halo (set below) wraps both lines.
+    const valueSize = Math.round(fontSize * 0.82);
+    t.append('tspan')
+      .attr('x', x)
+      .attr('dy', -fontSize * 0.28)
+      .text(text);
+    t.append('tspan')
+      .attr('x', x)
+      .attr('dy', fontSize * 0.92)
+      .attr('font-size', valueSize)
+      .attr('fill-opacity', 0.72)
+      .text(valueLine);
   } else {
     t.text(text);
   }

package/src/map/resolved-types.ts

@@ -4,7 +4,12 @@
 import type { DgmoError } from '../diagnostics';
 import type { TagGroup } from '../utils/tag-groups';
 import type { MapDirectives } from './types';
-import type { Gazetteer, BoundaryTopology, WaterBodies } from './data/types';
+import type {
+  Gazetteer,
+  BoundaryTopology,
+  WaterBodies,
+  AirportData,
+} from './data/types';
 
 /** The four static assets, injected into the pure resolver (DI). */
 export interface MapData {
@@ -32,6 +37,10 @@ export interface MapData {
    *  `context-labels` directive is on — oceans/seas/gulfs/bays/etc. Optional, so
    *  hand-built test fixtures and older bundles need not supply it. */
   waterBodies?: WaterBodies;
+  /** IATA-coded airports (`airports.json`) — lets `poi JFK` / `route JFK -> LAX`
+   *  resolve. Optional so hand-built fixtures and older DI bundles need not supply
+   *  it; the resolver guards `data.airports?.…` everywhere. */
+  airports?: AirportData;
   gazetteer: Gazetteer;
 }
 
@@ -40,6 +49,7 @@ export type ProjectionFamily =
   | 'natural-earth'
   | 'equirectangular'
   | 'albers-usa'
+  | 'conic-equal-area'
   | 'mercator';
 
 /** Which geometry layers the renderer draws. */
@@ -89,6 +99,8 @@ export interface ResolvedEdge {
   readonly directed: boolean;
   readonly style: 'straight' | 'arc';
   readonly meta: Readonly<Record<string, string>>;
+  /** Tag(s) on the edge line → colour the LINE (§24B.6). */
+  readonly tags: Readonly<Record<string, string>>;
   readonly lineNumber: number;
 }
 
@@ -98,6 +110,8 @@ export interface ResolvedRouteLeg {
   readonly label?: string;
   readonly style: 'straight' | 'arc';
   readonly value?: string; // leg thickness
+  /** Tag(s) on the leg line → colour the LINE (§24B.6). */
+  readonly tags: Readonly<Record<string, string>>;
   readonly lineNumber: number;
 }