@diagrammo/dgmo 0.20.3 → 0.21.0

package/dist/advanced.d.cts

@@ -4268,8 +4268,12 @@ interface MapScale {
 interface MapDirectives {
     region?: string;
     projection?: string;
-    metric?: string;
-    sizeMetric?: string;
+    /** Legend label for the region value ramp (`region-metric <label>`). */
+    regionMetric?: 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`). */
+    flowMetric?: string;
     scale?: MapScale;
     regionLabels?: string;
     poiLabels?: string;
@@ -4279,6 +4283,12 @@ interface MapDirectives {
     noLegend?: boolean;
     subtitle?: string;
     caption?: string;
+    /** Basemap dress override (bare flags `muted` / `natural`). Forces the
+     *  land/water styling regardless of whether a colouring dimension is active —
+     *  `muted` recedes to neutral grays, `natural` keeps the green/blue reference
+     *  dress. Absent → auto (muted iff a score/tag dimension is active). Lets two
+     *  maps in one deck share a look. */
+    basemapStyle?: 'muted' | 'natural';
 }
 /** A region-fill: a subdivision name with an optional score and/or tag values
  *  (§24B.3/.4 — BOTH may be present; bivariate seam). */
@@ -4288,15 +4298,16 @@ interface MapRegion {
      *  (`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;
+    /** Numeric value → choropleth shade (§24B.3). Lifted out of `meta`. */
+    readonly value?: number;
     /** Tag values keyed by lowercased tag GROUP name (alias is resolved away). */
     readonly tags: Readonly<Record<string, string>>;
-    /** Other reserved-but-inert keys (description/date/…) captured verbatim. */
+    /** Any remaining reserved keys captured verbatim (`label`/`style`/…). */
     readonly meta: Readonly<Record<string, string>>;
     readonly lineNumber: number;
 }
-/** A point of interest (§24B.5). `meta` holds reserved-but-inert keys
- *  (size/score/description/weight/date) verbatim; `label` is lifted out. */
+/** A point of interest (§24B.5). `meta` holds the numeric `value` (→ marker
+ *  size) and `style` verbatim; `label` is lifted out. */
 interface MapPoi {
     readonly pos: PoiPos;
     readonly alias?: string;
@@ -4305,17 +4316,31 @@ interface MapPoi {
     readonly meta: Readonly<Record<string, string>>;
     readonly lineNumber: number;
 }
-/** A route stop (§24B.6); raw order preserved incl. a repeated first==last (loop). */
-interface MapRouteStop {
-    readonly ref: PoiPos;
-    readonly alias?: string;
-    readonly meta: Readonly<Record<string, string>>;
+/** One leg of a route (§24B.6): an edge from the previous stop to `dest`. Reuses
+ *  the edge arrow idiom — in-arrow text = leg label, `value:` = leg thickness,
+ *  `->`/`~>` (or the header `style: arc`) = shape. Stop-targeted keys on the leg
+ *  line (`tag`, `label:`) decorate the DESTINATION point. */
+interface MapRouteLeg {
+    readonly label?: string;
+    readonly style: 'straight' | 'arc';
+    readonly value?: string;
+    readonly dest: PoiPos;
+    readonly destAlias?: string;
+    readonly destLabel?: string;
+    readonly destTags: Readonly<Record<string, string>>;
     readonly lineNumber: number;
 }
-/** An ordered, auto-numbered route (§24B.6). `meta.style==='arc'` curves legs. */
+/** An ordered, auto-numbered route (§24B.6): `route <origin> [style: arc]` + a
+ *  sequence of indented arrow legs, each continuing from the previous stop.
+ *  Repeat the origin as a leg's destination to close a loop. */
 interface MapRoute {
-    readonly stops: readonly MapRouteStop[];
-    readonly meta: Readonly<Record<string, string>>;
+    readonly origin: PoiPos;
+    readonly originAlias?: string;
+    readonly originLabel?: string;
+    readonly originValue?: string;
+    readonly originTags: Readonly<Record<string, string>>;
+    readonly style: 'straight' | 'arc';
+    readonly legs: readonly MapRouteLeg[];
     readonly lineNumber: number;
 }
 /** A connector (§24B.6). Endpoints are RAW identifier strings (name or alias);
@@ -4447,7 +4472,7 @@ interface ResolvedRegion {
     readonly iso: string;
     readonly name: string;
     readonly layer: 'country' | 'us-state';
-    readonly score?: number;
+    readonly value?: number;
     readonly tags: Readonly<Record<string, string>>;
     readonly meta: Readonly<Record<string, string>>;
     readonly lineNumber: number;
@@ -4477,9 +4502,19 @@ interface ResolvedEdge {
     readonly meta: Readonly<Record<string, string>>;
     readonly lineNumber: number;
 }
+interface ResolvedRouteLeg {
+    readonly fromId: string;
+    readonly toId: string;
+    readonly label?: string;
+    readonly style: 'straight' | 'arc';
+    readonly value?: string;
+    readonly lineNumber: number;
+}
 interface ResolvedRoute {
+    /** Ordered UNIQUE stop ids (for numbering + the origin marker). A loop-closing
+     *  leg whose destination is an earlier stop adds a leg but no duplicate stop. */
     readonly stopIds: readonly string[];
-    readonly meta: Readonly<Record<string, string>>;
+    readonly legs: readonly ResolvedRouteLeg[];
     readonly lineNumber: number;
 }
 /** Geographic bounding box `[[west, south], [east, north]]` in degrees.
@@ -4524,9 +4559,9 @@ 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>>;
@@ -4555,6 +4590,9 @@ interface MapLayoutPoi {
     readonly implicit: boolean;
     readonly isOrigin: boolean;
     readonly routeNumber?: number;
+    /** 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). */
 interface MapLayoutLeg {
@@ -4651,13 +4689,16 @@ interface Size {
 }
 /** 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). */
-declare function mapBackgroundColor(palette: PaletteColors): string;
-/** 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`. */
-declare function mapNeutralLandColor(palette: PaletteColors, isDark: boolean): 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. */
+declare function mapBackgroundColor(palette: PaletteColors, isDark?: boolean, dataActive?: boolean): string;
+/** 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`. */
+declare function mapNeutralLandColor(palette: PaletteColors, isDark: boolean, dataActive?: boolean): string;
 declare function layoutMap(resolved: ResolvedMap, data: MapData, size: Size, opts: LayoutOptions): MapLayout;
 
 /** Render a resolved map into `container` (d3-selection appends an `<svg>`). */

package/dist/advanced.d.ts

@@ -4268,8 +4268,12 @@ interface MapScale {
 interface MapDirectives {
     region?: string;
     projection?: string;
-    metric?: string;
-    sizeMetric?: string;
+    /** Legend label for the region value ramp (`region-metric <label>`). */
+    regionMetric?: 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`). */
+    flowMetric?: string;
     scale?: MapScale;
     regionLabels?: string;
     poiLabels?: string;
@@ -4279,6 +4283,12 @@ interface MapDirectives {
     noLegend?: boolean;
     subtitle?: string;
     caption?: string;
+    /** Basemap dress override (bare flags `muted` / `natural`). Forces the
+     *  land/water styling regardless of whether a colouring dimension is active —
+     *  `muted` recedes to neutral grays, `natural` keeps the green/blue reference
+     *  dress. Absent → auto (muted iff a score/tag dimension is active). Lets two
+     *  maps in one deck share a look. */
+    basemapStyle?: 'muted' | 'natural';
 }
 /** A region-fill: a subdivision name with an optional score and/or tag values
  *  (§24B.3/.4 — BOTH may be present; bivariate seam). */
@@ -4288,15 +4298,16 @@ interface MapRegion {
      *  (`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;
+    /** Numeric value → choropleth shade (§24B.3). Lifted out of `meta`. */
+    readonly value?: number;
     /** Tag values keyed by lowercased tag GROUP name (alias is resolved away). */
     readonly tags: Readonly<Record<string, string>>;
-    /** Other reserved-but-inert keys (description/date/…) captured verbatim. */
+    /** Any remaining reserved keys captured verbatim (`label`/`style`/…). */
     readonly meta: Readonly<Record<string, string>>;
     readonly lineNumber: number;
 }
-/** A point of interest (§24B.5). `meta` holds reserved-but-inert keys
- *  (size/score/description/weight/date) verbatim; `label` is lifted out. */
+/** A point of interest (§24B.5). `meta` holds the numeric `value` (→ marker
+ *  size) and `style` verbatim; `label` is lifted out. */
 interface MapPoi {
     readonly pos: PoiPos;
     readonly alias?: string;
@@ -4305,17 +4316,31 @@ interface MapPoi {
     readonly meta: Readonly<Record<string, string>>;
     readonly lineNumber: number;
 }
-/** A route stop (§24B.6); raw order preserved incl. a repeated first==last (loop). */
-interface MapRouteStop {
-    readonly ref: PoiPos;
-    readonly alias?: string;
-    readonly meta: Readonly<Record<string, string>>;
+/** One leg of a route (§24B.6): an edge from the previous stop to `dest`. Reuses
+ *  the edge arrow idiom — in-arrow text = leg label, `value:` = leg thickness,
+ *  `->`/`~>` (or the header `style: arc`) = shape. Stop-targeted keys on the leg
+ *  line (`tag`, `label:`) decorate the DESTINATION point. */
+interface MapRouteLeg {
+    readonly label?: string;
+    readonly style: 'straight' | 'arc';
+    readonly value?: string;
+    readonly dest: PoiPos;
+    readonly destAlias?: string;
+    readonly destLabel?: string;
+    readonly destTags: Readonly<Record<string, string>>;
     readonly lineNumber: number;
 }
-/** An ordered, auto-numbered route (§24B.6). `meta.style==='arc'` curves legs. */
+/** An ordered, auto-numbered route (§24B.6): `route <origin> [style: arc]` + a
+ *  sequence of indented arrow legs, each continuing from the previous stop.
+ *  Repeat the origin as a leg's destination to close a loop. */
 interface MapRoute {
-    readonly stops: readonly MapRouteStop[];
-    readonly meta: Readonly<Record<string, string>>;
+    readonly origin: PoiPos;
+    readonly originAlias?: string;
+    readonly originLabel?: string;
+    readonly originValue?: string;
+    readonly originTags: Readonly<Record<string, string>>;
+    readonly style: 'straight' | 'arc';
+    readonly legs: readonly MapRouteLeg[];
     readonly lineNumber: number;
 }
 /** A connector (§24B.6). Endpoints are RAW identifier strings (name or alias);
@@ -4447,7 +4472,7 @@ interface ResolvedRegion {
     readonly iso: string;
     readonly name: string;
     readonly layer: 'country' | 'us-state';
-    readonly score?: number;
+    readonly value?: number;
     readonly tags: Readonly<Record<string, string>>;
     readonly meta: Readonly<Record<string, string>>;
     readonly lineNumber: number;
@@ -4477,9 +4502,19 @@ interface ResolvedEdge {
     readonly meta: Readonly<Record<string, string>>;
     readonly lineNumber: number;
 }
+interface ResolvedRouteLeg {
+    readonly fromId: string;
+    readonly toId: string;
+    readonly label?: string;
+    readonly style: 'straight' | 'arc';
+    readonly value?: string;
+    readonly lineNumber: number;
+}
 interface ResolvedRoute {
+    /** Ordered UNIQUE stop ids (for numbering + the origin marker). A loop-closing
+     *  leg whose destination is an earlier stop adds a leg but no duplicate stop. */
     readonly stopIds: readonly string[];
-    readonly meta: Readonly<Record<string, string>>;
+    readonly legs: readonly ResolvedRouteLeg[];
     readonly lineNumber: number;
 }
 /** Geographic bounding box `[[west, south], [east, north]]` in degrees.
@@ -4524,9 +4559,9 @@ 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>>;
@@ -4555,6 +4590,9 @@ interface MapLayoutPoi {
     readonly implicit: boolean;
     readonly isOrigin: boolean;
     readonly routeNumber?: number;
+    /** 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). */
 interface MapLayoutLeg {
@@ -4651,13 +4689,16 @@ interface Size {
 }
 /** 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). */
-declare function mapBackgroundColor(palette: PaletteColors): string;
-/** 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`. */
-declare function mapNeutralLandColor(palette: PaletteColors, isDark: boolean): 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. */
+declare function mapBackgroundColor(palette: PaletteColors, isDark?: boolean, dataActive?: boolean): string;
+/** 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`. */
+declare function mapNeutralLandColor(palette: PaletteColors, isDark: boolean, dataActive?: boolean): string;
 declare function layoutMap(resolved: ResolvedMap, data: MapData, size: Size, opts: LayoutOptions): MapLayout;
 
 /** Render a resolved map into `container` (d3-selection appends an `<svg>`). */