@diagrammo/dgmo 0.21.1 → 0.23.0

package/docs/language-reference.md

@@ -1469,12 +1469,47 @@ Indented shorthand also supports groups (place arrow directly after group header
 ### 13.6 Directives
 
 - `direction TB` — top-to-bottom layout (default: `LR`)
+- `box-metric <Label> [color]` — name a numeric value dimension (see §13.8); optional trailing color sets the ramp hue
+- `show-values` — print each box's numeric value as text (off by default)
 
 ### 13.7 Options
 
 - `active-tag GroupName` — set active tag group for coloring
+- `active-tag none` — suppress tag coloring
+- `active-tag <metric>` — make the value ramp the active dimension (see §13.8)
 - `hide team:Backend, team:Frontend` — hide nodes with matching tag values (colon syntax for tag:value)
 
+### 13.8 Value metric (numeric ramp)
+
+Boxes can carry a numeric measure that drives a continuous color ramp — a
+choropleth-style "value dimension" alongside the categorical tag groups.
+
+```
+boxes-and-lines Fleet Crews
+box-metric Crew blue
+show-values
+
+Flagship value: 120
+Frigate value: 40
+Sloop value: 12
+Flagship -> Frigate
+Flagship -> Sloop
+```
+
+- `value: <number>` on any box records its measure (a reserved metadata key —
+  lifted out, never rendered as a tag). Non-numeric values are an error.
+- `box-metric <Label> [color]` names the dimension and optionally sets the ramp
+  hue (default: the palette's primary color).
+- The ramp anchors at `0` for all-non-negative data, else at the data minimum.
+- The value ramp is the resting-active dimension whenever any box has a
+  `value:` (so value shading works in static export with no interaction).
+  `active-tag <tag-group>` switches to a tag group; `active-tag none` suppresses
+  tinting; `active-tag <metric>` forces the value ramp. On a name collision
+  between a tag group and the metric label, the tag group wins.
+- When the value ramp is active, every box tints along the min→max ramp and the
+  legend shows a gradient capsule; boxes without a `value:` get a neutral fill.
+- `show-values` additionally prints each box's number as text.
+
 ---
 
 ## 15. Timeline Diagrams
@@ -2644,7 +2679,9 @@ Markers in cells are always **rendered in canonical alphabet order** (`R A C I`,
 
 Geographic concept maps: highlight/shade political subdivisions, drop points of interest (POIs), and connect them with routes or edges. For "share a concept" business maps, not cartography. Renders at a fixed, auto-fit position — no pan/zoom. Basemap and viewport are **inferred from the content you reference** — most maps need no directives. v1 boundaries: world countries + US states.
 
-**How the map type is decided (inference):** the resolver takes the bounding box of everything referenced (valued/tagged regions + POIs + edge endpoints), pads it, and measures its span. Projection: `albers-usa` (US conic + AK/HI insets) when the map is US-only; else `equirectangular` snapped to the full Greenwich world when the span is world-scale (≥ ~90°); else `mercator` for a tight regional cluster; else `equirectangular`. The US-state mesh is added whenever you name a US state. Directives only matter to *override* this: `region us-states` forces the state mesh + US scoping (useful on a POI-only US map, redundant once you name a state); `projection …` forces the projection; **`region world` is currently inert** — world is already the default, so it changes nothing (the frame widens from a world-scale longitude span, not this directive).
+**The zero-config map is the good-looking map.** Type `map`, name some places, and you're done — coastlines, mountain relief (on reference maps), region/POI labels, and orientation labels all render by default. There is no projection, scale, or label directive; the only knobs are the bare `no-*` opt-outs.
+
+**How the map type is decided (inference):** the resolver takes the bounding box of everything referenced (valued/tagged regions + POIs + edge endpoints), pads it, and measures its span. Projection is **always inferred — never configured**: `albers-usa` (US conic + AK/HI insets) when the map is US-oriented; at world/multi-continent scale a **data** map (any region/POI carries `value:` or a tag) gets **Equal Earth** (equal-area — honest for thematic comparison) while a **dataless reference** map gets **natural-earth** (the prettier curved compromise); `mercator` for a tight regional or single-continent cluster. The US-state mesh is added whenever you name a US state (or the map is US-oriented).
 
 ### Declaration
 
@@ -2660,7 +2697,6 @@ A subdivision name on its own line with a `value:` fills with a single-hue tint
 
 ```
 map US Sales
-region us-states
 region-metric Sales ($M)
 
 California value: 92
@@ -2668,7 +2704,8 @@ Texas value: 78
 Florida value: 51
 ```
 
-- `region-metric <label>` labels the ramp in the legend; a trailing color on it sets the ramp hue (`region-metric Sales ($M) blue` → blue ramp, default red). `scale <min> <max>` overrides the auto anchors.
+- `region-metric <label>` labels the ramp in the legend; a trailing color on it sets the ramp hue (`region-metric Sales ($M) blue` → blue ramp, default red).
+- The ramp **auto-fits**: all-non-negative data anchors the low end at **0** (shared baseline); mixed-sign data fits data-min→data-max. There is no `scale` directive.
 - A subdivision with no `value:`/tag renders as the neutral base.
 
 ### Region fill — categorical (tags)
@@ -2677,7 +2714,6 @@ Uses the universal tag model (§1.3): declare a `tag` group and apply its alias
 
 ```
 map Global Presence
-region world
 
 tag Market as m
   HQ blue
@@ -2734,18 +2770,28 @@ dcw                     # hub/star — indented edges share the source
   -> office-west
 ```
 
-`~>` curves a single edge. No geographic path-finding — legs are straight or arced.
+`~>` curves a single edge. There is no geographic path-finding and no `surface:` — legs are plain straight or arced geometry (`style: arc` to bow one) and may cross land.
+
+```
+map Caribbean Cruise
+
+route Miami style: arc
+  -weigh anchor-> Havana
+  -> Kingston
+  -> Cartagena
+```
 
 ### Labels, legend & chrome
 
-- Title is the declaration line; `subtitle` / `caption` are directives.
+- Title is the declaration line; `caption` (data-source attribution, travels with the exported PNG) is the only chrome directive. There is no `subtitle`.
 - Legend auto-composes below the title: the value ramp + `region-metric` and each tag group are **selectable colouring groups** (collapse/activate to flip the fill); POI size (`poi-metric`) and edge thickness (`flow-metric`) are self-evident from scale and carry no legend key in v1. `no-legend` suppresses all of it.
-- `region-labels full | abbrev | off` (default `off`); `poi-labels off | auto | all` (default `auto`). Labels render **on the map** (export-safe), escalating inline → leader line → numbered pin in dense clusters; markers never move.
+- **Region and POI labels are on by default.** Region labels auto-fit **full → abbrev → hide** (a US-state 2-letter abbreviation is tried when the full name doesn't fit; other regions degrade full → hide); POI labels are collision-managed. Labels render **on the map** (export-safe), escalating inline → leader line → numbered pin in dense clusters; markers never move. A wide map in a narrow column (< ~480px) prefers abbreviations and drops reference relief, as if zoomed out.
+- **Cosmetic features are on by default**; the only switches are bare `no-*` opt-outs (no positive opt-in flag): `no-coastline`, `no-relief`, `no-context-labels`, `no-region-labels`, `no-poi-labels`, `no-legend`. A plain look = the four basemap flags together.
 
 ### Name resolution
 
 - Admin units use **ISO 3166** (geometry keyed by code, so "United States" / "USA" / "US" resolve alike); cities use **GeoNames** (alias/accent matching, population ranking, did-you-mean).
-- `default-country` / `default-state <ISO>` scopes bare city resolution (inferred from content if unset).
+- `locale <ISO>` scopes bare city resolution to a country (`locale US`) or subdivision (`locale US-GA`) — inferred from content if unset.
 - A bare ambiguous, undeclared name → most-populous in scope (info note).
 - **Disambiguate once:** trailing ISO code at first declaration — `San Jose CR` (country) or `Portland US-OR` (subdivision). Thereafter reference the bare name. Two same-named cities → `as <alias>` each.
 - **Region fills disambiguate the country-vs-state collision** (`Georgia` = country `GE` or US state `US-GA`) by ISO code or name + scope — pick whichever reads best:
@@ -2756,7 +2802,7 @@ dcw                     # hub/star — indented edges share the source
 
 ### Directives & reserved keys
 
-Directives (no colon): `region` (world | us-states), `projection` (equirectangular | natural-earth | albers-usa | mercator), `region-metric`, `poi-metric`, `flow-metric`, `scale`, `region-labels`, `poi-labels`, `default-country`, `default-state`, `active-tag`, `no-legend`, `subtitle`, `caption`. Reserved metadata keys (need colons): `value`, `label`, `style` (`value` = the one numeric channel: region shade / POI size / edge thickness). A bare US state postal code resolves to that state (`poi Portland OR` → Oregon; `CA` = California). Coordinates are positional (no `at:` key). Projection is auto-picked by extent span (world → equirectangular, full Greenwich frame; US → albers-usa with Alaska/Hawaii insets; tight regional → mercator) unless overridden.
+The directive set is **12, all colon-free**: six naming intent the renderer can't infer — `region-metric`, `poi-metric`, `flow-metric`, `locale`, `active-tag`, `caption` — and six `no-*` cosmetic opt-outs — `no-legend`, `no-coastline`, `no-relief`, `no-context-labels`, `no-region-labels`, `no-poi-labels`. There is **no** `projection`, `scale`, `subtitle`, `surface`, `region`, or label-enum directive, and cosmetics have no positive opt-in form. Reserved metadata keys (need colons): `value`, `label`, `style` (`value` = the one numeric channel: region shade / POI size / edge thickness); `surface:` is no longer recognized. A bare US state postal code resolves to that state (`poi Portland OR` → Oregon; `CA` = California). Coordinates are positional (no `at:` key). Projection is inferred from extent + whether the map carries data (US → albers-usa; world data → Equal Earth; world reference → natural-earth; regional → mercator) and cannot be overridden.
 
 ---
 

package/gallery/fixtures/boxes-and-lines.dgmo

@@ -6,28 +6,30 @@ tag Priority p High red, Medium orange, Low gray
 active-tag Team
 hide priority:Low
 
+box-metric Load orange
+
 direction LR
 
 // --- Services ---
-API Gateway t: Backend
+API Gateway t: Backend, value: 850
   Main entry point for all requests
   Routes to **backend services**
   -routes-> UserService
   -routes-> ProductService
   -routes-> OrderService
 
-UserService t: Backend
+UserService t: Backend, value: 430
   Handles auth and profiles
   Uses `JWT` tokens for sessions
   -reads-> UserDB
   -checks-> SessionCache
 
-ProductService t: Frontend, description: Product catalog and search
+ProductService t: Frontend, value: 620, description: Product catalog and search
   Supports *full-text* search
   -queries-> ProductDB
   -invalidates-> ProductCache
 
-OrderService t: Backend
+OrderService t: Backend, value: 290
   Order processing pipeline
   Validates inventory before commit
   -writes-> OrderDB

package/gallery/fixtures/map-categorical-world.dgmo

@@ -0,0 +1,16 @@
+map Global Market Presence
+
+tag Market as m
+  HQ blue
+  Region teal
+  Prospect orange
+active-tag Market
+
+United States m: HQ
+Germany m: Region
+Japan m: Region
+Brazil m: Prospect
+India m: Region
+Australia m: Prospect
+South Africa m: Prospect
+Indonesia m: Prospect

package/gallery/fixtures/map-categorical.dgmo

@@ -1,5 +1,4 @@
 map Global Market Presence
-region world
 
 tag Market as m
   HQ blue

package/gallery/fixtures/map-choropleth.dgmo

@@ -1,5 +1,4 @@
 map US Sales by State
-region us-states
 region-metric Sales ($M)
 
 California value: 92

package/gallery/fixtures/map-coastline.dgmo

@@ -0,0 +1,7 @@
+map Smuggler's Run
+
+poi Havana value: 90
+poi Kingston value: 120
+
+route Havana style: arc
+  -run the blockade-> Kingston

package/gallery/fixtures/map-colorize.dgmo

@@ -0,0 +1,11 @@
+map Privateer's Atlas
+
+// Regions named, no value: or tags → colorize is the inferred dress: every
+// state/country gets a distinct pastel and no two neighbours share a hue
+// (4-colour political look). The named states aren't special — the whole drawn
+// mesh colours, so it reads as one chart. `no-colorize` would force green-land.
+California
+Texas
+Florida
+New York
+Washington

package/gallery/fixtures/map-direct-color.dgmo

@@ -1,5 +1,4 @@
 map Regional Focus
-region us-states
 region-metric Sales ($M) blue
 
 California value: 92

package/gallery/fixtures/map-reference-world.dgmo

@@ -0,0 +1,11 @@
+map World Reference
+
+// A dataless reference map (regions named, no value: or tags) — so the
+// zero-config basemap shows its full dress: coastline water-lines, mountain
+// relief, and orientation labels, on a natural-earth projection.
+United States
+Brazil
+Egypt
+India
+Japan
+Australia

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

@@ -1,8 +1,5 @@
 map Region Scope Disambiguation
-region us-states
 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 value: 92
 Texas value: 78

package/gallery/fixtures/map-route.dgmo

@@ -1,5 +1,4 @@
 map Caribbean Cruise
-projection mercator
 
 route Miami style: arc
   -weigh anchor-> Havana

package/package.json

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

package/src/advanced.ts

@@ -540,6 +540,14 @@ export type {
   MapLayoutLegend,
 } from './map/layout';
 export { renderMap, renderMapForExport } from './map/renderer';
+// Content-aware export dimensions — derive the canvas height from a map's intrinsic
+// projected aspect so exports/embeds match the content's natural shape (no vertical
+// stretch). Used by the CLI/MCP/SSG export path and by Obsidian's DI render.
+export {
+  mapContentAspect,
+  mapExportDimensions,
+  type MapExportDimensions,
+} from './map/dimensions';
 // Map geo-query (step-5 coordinate/location inspector) — a SEPARATE entry from
 // the renderer; takes `MapData` by DI so it's browser-safe (never calls the
 // Node-only `loadMapData`).
@@ -734,7 +742,10 @@ export {
   gruvboxPalette,
   tokyoNightPalette,
   oneDarkPalette,
-  boldPalette,
+  atlasPalette,
+  blueprintPalette,
+  slatePalette,
+  tidewaterPalette,
   draculaPalette,
   monokaiPalette,
 } from './palettes';

package/src/boxes-and-lines/parser.ts

@@ -26,6 +26,7 @@ import {
   extractColor,
   parseFirstLine,
   OPTION_NOCOLON_RE,
+  peelTrailingColorName,
   splitNameAndMeta,
   tryParseSharedOption,
   warnUnknownMetaKeys,
@@ -297,6 +298,26 @@ export function parseBoxesAndLines(content: string): ParsedBoxesAndLines {
         continue;
       }
 
+      // box-metric / show-values directives — pre-content only (like
+      // active-tag). Explicit regex branches: a bare flag and a
+      // `key value` form won't both match the active-tag OPTION codepath.
+      if (!contentStarted) {
+        const metricMatch = trimmed.match(/^box-metric\s+(.+)$/i);
+        if (metricMatch) {
+          // Regex capture group present after successful match.
+          const { label, colorName } = peelTrailingColorName(
+            metricMatch[1]!.trim()
+          );
+          result.boxMetric = label;
+          if (colorName !== undefined) result.boxMetricColor = colorName;
+          continue;
+        }
+        if (/^show-values$/i.test(trimmed)) {
+          result.showValues = true;
+          continue;
+        }
+      }
+
       // active-tag directive
       if (!contentStarted) {
         const optMatch = trimmed.match(OPTION_NOCOLON_RE);
@@ -784,6 +805,23 @@ function parseNodeLine(
     delete metadata['description'];
   }
 
+  // Lift `value: X` out of metadata into a typed numeric field (mirror of the
+  // map parser). Validate finite-numeric; delete from metadata so it never
+  // becomes a `data-tag-value` attribute.
+  let value: number | undefined;
+  if (metadata['value'] !== undefined) {
+    const raw = metadata['value'];
+    const num = Number(raw);
+    if (Number.isFinite(num)) {
+      value = num;
+    } else {
+      diagnostics.push(
+        makeDgmoError(lineNum, `value must be a number (got "${raw}")`, 'error')
+      );
+    }
+    delete metadata['value'];
+  }
+
   // TD-18 alias is now peeled by splitNameAndMeta — re-register if set.
   if (split.alias) {
     nameAliasMap?.set(normalizeName(split.alias), label);
@@ -796,6 +834,7 @@ function parseNodeLine(
     lineNumber: lineNum,
     metadata,
     ...(description !== undefined && { description }),
+    ...(value !== undefined && { value }),
   };
 }