@diagrammo/dgmo 0.19.0 → 0.20.1

package/src/map/renderer.ts

@@ -17,7 +17,7 @@ import type { LegendConfig, LegendState } from '../utils/legend-types';
 import type { PaletteColors } from '../palettes/types';
 import type { D3ExportDimensions } from '../utils/d3-types';
 import type { MapData, ResolvedMap } from './resolved-types';
-import { layoutMap, type MapLayout, type PlacedLabel } from './layout';
+import { layoutMap, type MapLayoutRegion, type PlacedLabel } from './layout';
 
 const LABEL_FONT = 11;
 
@@ -29,7 +29,9 @@ export function renderMap(
   palette: PaletteColors,
   isDark: boolean,
   onClickItem?: (lineNumber: number) => void,
-  exportDims?: D3ExportDimensions
+  exportDims?: D3ExportDimensions,
+  /** Live override of the active colouring group (interactive legend flip). */
+  activeGroupOverride?: string | null
 ): void {
   d3Selection.select(container).selectAll(':not([data-d3-tooltip])').remove();
   const width = exportDims?.width ?? container.clientWidth;
@@ -43,6 +45,9 @@ export function renderMap(
     {
       palette,
       isDark,
+      ...(activeGroupOverride !== undefined && {
+        activeGroup: activeGroupOverride,
+      }),
     }
   );
 
@@ -54,7 +59,12 @@ export function renderMap(
     .attr('viewBox', `0 0 ${width} ${height}`)
     .attr('preserveAspectRatio', 'xMidYMin meet')
     .attr('xmlns', 'http://www.w3.org/2000/svg')
-    .style('font-family', FONT_FAMILY);
+    .style('font-family', FONT_FAMILY)
+    // Match the SVG element background to the water rect so any letterboxing
+    // (when the host container's aspect differs from the viewBox) shows water,
+    // not the gray palette bg that finalizeSvgExport would otherwise apply —
+    // i.e. no stray band above/below the map.
+    .style('background', layout.background);
 
   svg
     .append('rect')
@@ -62,66 +72,46 @@ export function renderMap(
     .attr('height', height)
     .attr('fill', layout.background);
 
-  // Arrowhead marker for directed legs.
-  const arrowColor = mix(palette.text, palette.bg, 50);
+  // Arrowhead markers for directed legs. Sized in user-space (NOT the SVG
+  // default of stroke-width units) so a heavy weighted line doesn't blow the
+  // arrowhead up to a giant wedge. The size grows gently with the line width —
+  // enough to stay distinct from the stroke — but is firmly capped.
   const defs = svg.append('defs');
-  defs
-    .append('marker')
-    .attr('id', 'dgmo-map-arrow')
-    .attr('viewBox', '0 0 10 10')
-    .attr('refX', 9)
-    .attr('refY', 5)
-    .attr('markerWidth', 7)
-    .attr('markerHeight', 7)
-    .attr('orient', 'auto-start-reverse')
-    .append('path')
-    .attr('d', 'M0,0L10,5L0,10z')
-    .attr('fill', arrowColor);
+  // Dampened: ~8px at the thinnest leg, easing toward a 15px cap as legs widen.
+  const arrowSize = (w: number): number => Math.min(15, 7 + w * 0.95);
 
-  const haloColor = layout.background;
+  // Neutral bg (not the water-tinted backdrop) so label halos read over both
+  // land and ocean.
+  const haloColor = palette.bg;
 
-  // ── Title / subtitle ──
-  if (layout.title) {
-    svg
-      .append('text')
-      .attr('x', width / 2)
-      .attr('y', TITLE_Y)
-      .attr('text-anchor', 'middle')
-      .attr('font-size', TITLE_FONT_SIZE)
-      .attr('font-weight', TITLE_FONT_WEIGHT)
-      .attr('fill', palette.text)
-      .text(layout.title);
-  }
-  if (layout.subtitle) {
-    svg
-      .append('text')
-      .attr('x', width / 2)
-      .attr('y', TITLE_Y + TITLE_FONT_SIZE)
-      .attr('text-anchor', 'middle')
-      .attr('font-size', LABEL_FONT + 1)
-      .attr('fill', palette.textMuted)
-      .text(layout.subtitle);
-  }
-  if (layout.caption) {
-    svg
-      .append('text')
-      .attr('x', width / 2)
-      .attr('y', height - 8)
-      .attr('text-anchor', 'middle')
-      .attr('font-size', LABEL_FONT)
-      .attr('fill', palette.textMuted)
-      .text(layout.caption);
-  }
+  // Title / subtitle / caption are rendered LAST (see end of function) so they
+  // sit in the foreground above the basemap, POIs, and labels.
 
   // ── Regions ──
   const gRegions = svg.append('g').attr('class', 'dgmo-map-regions');
-  for (const r of layout.regions) {
-    const p = gRegions
+  const drawRegion = (
+    g: Sel,
+    r: MapLayoutRegion,
+    strokeWidth: number
+  ): void => {
+    const p = g
       .append('path')
       .attr('d', r.d)
       .attr('fill', r.fill)
       .attr('stroke', r.stroke)
-      .attr('stroke-width', 0.5);
+      .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
+    // (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.tags) {
+        for (const [group, value] of Object.entries(r.tags)) {
+          p.attr(`data-tag-${group.toLowerCase()}`, value.toLowerCase());
+        }
+      }
+    }
     if (r.lineNumber >= 0) {
       p.attr('data-line-number', r.lineNumber);
       if (onClickItem) {
@@ -130,6 +120,46 @@ export function renderMap(
         );
       }
     }
+  };
+  for (const r of layout.regions) drawRegion(gRegions, r, 0.5);
+
+  // ── Rivers (thin water centerlines over the land, under POIs/edges) ──
+  if (layout.rivers.length) {
+    const gRivers = svg
+      .append('g')
+      .attr('class', 'dgmo-map-rivers')
+      .attr('fill', 'none');
+    for (const r of layout.rivers) {
+      gRivers
+        .append('path')
+        .attr('d', r.d)
+        .attr('stroke', r.color)
+        .attr('stroke-width', r.width)
+        .attr('stroke-linecap', 'round')
+        .attr('stroke-linejoin', 'round');
+    }
+  }
+
+  // ── 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. ──
+  if (layout.insets.length) {
+    const insetG = svg.append('g').attr('class', 'dgmo-map-insets');
+    for (const box of layout.insets) {
+      // Angled-top quad frame — rides under the conus coast so it never covers
+      // neighbouring states. Closed path from the four corners.
+      const d =
+        box.points.map((p, i) => `${i ? 'L' : 'M'}${p[0]},${p[1]}`).join('') +
+        'Z';
+      insetG
+        .append('path')
+        .attr('d', d)
+        .attr('fill', layout.background)
+        .attr('stroke', mix(palette.text, palette.bg, 55))
+        .attr('stroke-width', 1)
+        .attr('stroke-linejoin', 'round');
+    }
+    for (const r of layout.insetRegions) drawRegion(insetG, r, 0.5);
   }
 
   // ── Legs (edges + route legs) ──
@@ -137,14 +167,31 @@ export function renderMap(
     .append('g')
     .attr('class', 'dgmo-map-legs')
     .attr('fill', 'none');
-  for (const leg of layout.legs) {
+  layout.legs.forEach((leg, i) => {
     const p = gLegs
       .append('path')
       .attr('d', leg.d)
       .attr('stroke', leg.color)
       .attr('stroke-width', leg.width)
       .attr('stroke-linecap', 'round');
-    if (leg.arrow) p.attr('marker-end', 'url(#dgmo-map-arrow)');
+    if (leg.arrow) {
+      const id = `dgmo-map-arrow-${i}`;
+      const s = arrowSize(leg.width);
+      defs
+        .append('marker')
+        .attr('id', id)
+        .attr('viewBox', '0 0 10 10')
+        .attr('refX', 10)
+        .attr('refY', 5)
+        .attr('markerUnits', 'userSpaceOnUse')
+        .attr('markerWidth', s)
+        .attr('markerHeight', s)
+        .attr('orient', 'auto-start-reverse')
+        .append('path')
+        .attr('d', 'M0,0L10,5L0,10z')
+        .attr('fill', leg.color);
+      p.attr('marker-end', `url(#${id})`);
+    }
     if (leg.label !== undefined && leg.labelX !== undefined) {
       emitText(
         gLegs,
@@ -158,7 +205,7 @@ export function renderMap(
         LABEL_FONT - 1
       );
     }
-  }
+  });
 
   // ── POIs ──
   const gPois = svg.append('g').attr('class', 'dgmo-map-pois');
@@ -181,7 +228,8 @@ export function renderMap(
       .attr('fill', poi.fill)
       .attr('stroke', poi.stroke)
       .attr('stroke-width', 1)
-      .attr('data-line-number', poi.lineNumber);
+      .attr('data-line-number', poi.lineNumber)
+      .attr('data-poi', poi.id);
     if (onClickItem) {
       c.style('cursor', 'pointer').on('click', () =>
         onClickItem(poi.lineNumber)
@@ -202,61 +250,40 @@ export function renderMap(
     }
   }
 
-  // ── Labels (leaders, halo text, numbered pins) ──
+  // ── Labels (leaders + halo text) ──
   const gLabels = svg.append('g').attr('class', 'dgmo-map-labels');
   for (const lab of layout.labels) {
     if (lab.leader) {
-      gLabels
+      const line = gLabels
         .append('line')
         .attr('x1', lab.leader.x1)
         .attr('y1', lab.leader.y1)
         .attr('x2', lab.leader.x2)
         .attr('y2', lab.leader.y2)
-        .attr('stroke', mix(palette.textMuted, palette.bg, 60))
-        .attr('stroke-width', 0.75);
+        // Tie the leader to its dot by colour; neutral grey when it has none.
+        .attr(
+          'stroke',
+          lab.leaderColor ?? mix(palette.textMuted, palette.bg, 60)
+        )
+        .attr('stroke-width', lab.leaderColor ? 1 : 0.75);
+      if (lab.poiId !== undefined) line.attr('data-poi', lab.poiId);
     }
-    if (lab.pin !== undefined) {
-      gLabels
-        .append('rect')
-        .attr('x', lab.x - 1)
-        .attr('y', lab.y - LABEL_FONT)
-        .attr('width', LABEL_FONT * 1.3)
-        .attr('height', LABEL_FONT * 1.3)
-        .attr('rx', 2)
-        .attr('fill', palette.surface)
-        .attr('stroke', palette.border);
-    }
-    emitText(
+    const t = emitText(
       gLabels,
       lab.x,
       lab.y,
       lab.text,
       lab.anchor,
       lab.color,
-      haloColor,
+      lab.haloColor,
       lab.halo,
       LABEL_FONT
     );
-  }
-
-  // ── Pin legend list ──
-  if (layout.pinList.length > 0) {
-    const gPins = svg
-      .append('g')
-      .attr('class', 'dgmo-map-pin-list')
-      .attr(
-        'transform',
-        `translate(12, ${height - layout.pinList.length * 14 - 8})`
-      );
-    layout.pinList.forEach((entry, i) => {
-      gPins
-        .append('text')
-        .attr('x', 0)
-        .attr('y', i * 14)
-        .attr('font-size', LABEL_FONT - 1)
-        .attr('fill', palette.textMuted)
-        .text(`${entry.pin} — ${entry.label}`);
-    });
+    // 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).
+    if (lab.poiId !== undefined) {
+      t.attr('data-poi', lab.poiId).style('cursor', 'default');
+    }
   }
 
   // ── Legend (categorical via renderLegendD3 + ramp/size/weight blocks; AR1) ──
@@ -269,21 +296,92 @@ export function renderMap(
       .append('g')
       .attr('class', 'dgmo-map-legend')
       .attr('transform', `translate(0, ${legendY})`);
-    const groups = layout.legend.tagGroups.filter((g) => g.entries.length > 0);
+    // The score 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.
+    const ramp = layout.legend.ramp;
+    const scoreGroup = ramp
+      ? {
+          name: ramp.metric?.trim() || 'Score',
+          entries: [],
+          gradient: {
+            min: ramp.min,
+            max: ramp.max,
+            hue: ramp.hue,
+            base: ramp.base,
+          },
+        }
+      : null;
+    const tagGroups = layout.legend.tagGroups
+      .filter((g) => g.entries.length > 0)
+      .map((g) => ({ name: g.name, entries: [...g.entries] }));
+    const groups = [...(scoreGroup ? [scoreGroup] : []), ...tagGroups];
     if (groups.length > 0) {
       const config: LegendConfig = {
-        groups: groups.map((g) => ({ name: g.name, entries: [...g.entries] })),
+        groups,
         position: { placement: 'top-center', titleRelation: 'below-title' },
         mode: exportDims ? 'export' : 'preview',
         showEmptyGroups: false,
+        // Keep inactive siblings visible as pills so the user can click to flip
+        // the active colouring dimension (preview only — export shows just the
+        // active group).
+        showInactivePills: true,
       };
       const state: LegendState = { activeGroup: layout.legend.activeGroup };
       renderLegendD3(legendG, config, state, palette, isDark, undefined, width);
     }
-    // Custom keys (ramp / size / weight), stacked above the pin list so they
-    // never overlap it (#3).
-    const pinGap = layout.pinList.length ? layout.pinList.length * 14 + 14 : 0;
-    emitExtraLegend(svg, layout, palette, height, pinGap);
+  }
+
+  // ── 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).
+  if (layout.title) {
+    svg
+      .append('text')
+      .attr('x', width / 2)
+      .attr('y', TITLE_Y)
+      .attr('text-anchor', 'middle')
+      .attr('font-size', TITLE_FONT_SIZE)
+      .attr('font-weight', TITLE_FONT_WEIGHT)
+      .attr('fill', palette.text)
+      .attr('paint-order', 'stroke fill')
+      .attr('stroke', palette.bg)
+      .attr('stroke-width', 4)
+      .attr('stroke-linejoin', 'round')
+      .attr('stroke-opacity', 0.7)
+      .text(layout.title);
+  }
+  if (layout.subtitle) {
+    svg
+      .append('text')
+      .attr('x', width / 2)
+      .attr('y', TITLE_Y + TITLE_FONT_SIZE)
+      .attr('text-anchor', 'middle')
+      .attr('font-size', LABEL_FONT + 1)
+      .attr('fill', palette.textMuted)
+      .attr('paint-order', 'stroke fill')
+      .attr('stroke', palette.bg)
+      .attr('stroke-width', 3)
+      .attr('stroke-linejoin', 'round')
+      .attr('stroke-opacity', 0.7)
+      .text(layout.subtitle);
+  }
+  if (layout.caption) {
+    svg
+      .append('text')
+      .attr('x', width / 2)
+      .attr('y', height - 8)
+      .attr('text-anchor', 'middle')
+      .attr('font-size', LABEL_FONT)
+      .attr('fill', palette.textMuted)
+      .attr('paint-order', 'stroke fill')
+      .attr('stroke', palette.bg)
+      .attr('stroke-width', 3)
+      .attr('stroke-linejoin', 'round')
+      .attr('stroke-opacity', 0.7)
+      .text(layout.caption);
   }
 }
 
@@ -300,7 +398,6 @@ export function renderMapForExport(
 }
 
 type Sel = d3Selection.Selection<SVGGElement, unknown, null, undefined>;
-type SvgSel = d3Selection.Selection<SVGSVGElement, unknown, null, undefined>;
 
 function emitText(
   g: Sel,
@@ -312,7 +409,7 @@ function emitText(
   halo: string,
   withHalo: boolean,
   fontSize: number
-): void {
+): d3Selection.Selection<SVGTextElement, unknown, null, undefined> {
   const t = g
     .append('text')
     .attr('x', x)
@@ -328,121 +425,5 @@ function emitText(
       .attr('stroke-linejoin', 'round')
       .attr('stroke-opacity', 0.7);
   }
-}
-
-/** Ramp gradient bar + graduated size/weight keys (not legend swatch groups). */
-function emitExtraLegend(
-  svg: SvgSel,
-  layout: MapLayout,
-  palette: PaletteColors,
-  height: number,
-  bottomGap: number
-): void {
-  const { legend } = layout;
-  if (!legend) return;
-  // Nothing to draw if there are only categorical swatches (#4).
-  if (!legend.ramp && !legend.size && !legend.weight) return;
-  const blocks: Array<() => void> = [];
-  const g = svg
-    .append('g')
-    .attr('class', 'dgmo-map-legend-keys')
-    .attr('transform', `translate(12, ${height - 56 - bottomGap})`);
-  let xCursor = 0;
-
-  if (legend.ramp) {
-    const ramp = legend.ramp;
-    blocks.push(() => {
-      const block = g.append('g').attr('transform', `translate(${xCursor},0)`);
-      const gradId = 'dgmo-map-ramp';
-      const grad = block
-        .append('defs')
-        .append('linearGradient')
-        .attr('id', gradId)
-        .attr('x1', '0%')
-        .attr('x2', '100%');
-      grad
-        .append('stop')
-        .attr('offset', '0%')
-        .attr('stop-color', mix(ramp.hue, palette.bg, 15));
-      grad.append('stop').attr('offset', '100%').attr('stop-color', ramp.hue);
-      block
-        .append('rect')
-        .attr('width', 80)
-        .attr('height', 8)
-        .attr('fill', `url(#${gradId})`);
-      block
-        .append('text')
-        .attr('x', 0)
-        .attr('y', 22)
-        .attr('font-size', 9)
-        .attr('fill', palette.textMuted)
-        .text(String(ramp.min));
-      block
-        .append('text')
-        .attr('x', 80)
-        .attr('y', 22)
-        .attr('text-anchor', 'end')
-        .attr('font-size', 9)
-        .attr('fill', palette.textMuted)
-        .text(String(ramp.max));
-      if (ramp.metric) {
-        block
-          .append('text')
-          .attr('x', 0)
-          .attr('y', -4)
-          .attr('font-size', 9)
-          .attr('fill', palette.textMuted)
-          .text(ramp.metric);
-      }
-      xCursor += 110;
-    });
-  }
-  if (legend.size) {
-    const sz = legend.size;
-    blocks.push(() => {
-      const block = g.append('g').attr('transform', `translate(${xCursor},0)`);
-      [3, 6, 10].forEach((r, i) => {
-        block
-          .append('circle')
-          .attr('cx', i * 26 + r)
-          .attr('cy', 8)
-          .attr('r', r)
-          .attr('fill', 'none')
-          .attr('stroke', palette.textMuted);
-      });
-      block
-        .append('text')
-        .attr('x', 0)
-        .attr('y', -4)
-        .attr('font-size', 9)
-        .attr('fill', palette.textMuted)
-        .text(sz.metric ?? 'size');
-      xCursor += 110;
-    });
-  }
-  if (legend.weight) {
-    const wt = legend.weight;
-    blocks.push(() => {
-      const block = g.append('g').attr('transform', `translate(${xCursor},0)`);
-      [1, 3, 6].forEach((w, i) => {
-        block
-          .append('line')
-          .attr('x1', i * 26)
-          .attr('y1', 8)
-          .attr('x2', i * 26 + 20)
-          .attr('y2', 8)
-          .attr('stroke', palette.textMuted)
-          .attr('stroke-width', w);
-      });
-      block
-        .append('text')
-        .attr('x', 0)
-        .attr('y', -4)
-        .attr('font-size', 9)
-        .attr('fill', palette.textMuted)
-        .text(wt.metric ?? 'weight');
-      xCursor += 110;
-    });
-  }
-  for (const draw of blocks) draw();
+  return t;
 }

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 {