@diagrammo/dgmo 0.32.1 → 0.34.0

package/src/org/renderer.ts

@@ -2,6 +2,7 @@
 // Org Chart SVG Renderer
 // ============================================================
 
+import { tagAttrKey } from '../utils/tag-groups';
 import * as d3Selection from 'd3-selection';
 import { FONT_FAMILY } from '../fonts';
 import {
@@ -269,7 +270,7 @@ export function renderOrg(
   // Build display name map from tag groups (lowercase key → original casing)
   const displayNames = new Map<string, string>();
   for (const group of parsed.tagGroups) {
-    displayNames.set(group.name.toLowerCase(), group.name);
+    displayNames.set(tagAttrKey(group.name), group.name);
   }
 
   // Root node IDs — focus icon is suppressed on these (already the tree root)
@@ -288,7 +289,7 @@ export function renderOrg(
     // Use tagMetadata (unfiltered) so hover-highlight works even when the
     // active tag group is hidden from the visible card body via the eye toggle.
     if (activeTagGroup) {
-      const tagKey = activeTagGroup.toLowerCase();
+      const tagKey = tagAttrKey(activeTagGroup);
       const metaValue = c.tagMetadata[tagKey];
       if (metaValue) {
         cG.attr(`data-tag-${tagKey}`, metaValue.toLowerCase());
@@ -466,7 +467,7 @@ export function renderOrg(
     // Use tagMetadata (unfiltered) so hover-highlight works even when the
     // active tag group is hidden from the visible card body via the eye toggle.
     if (activeTagGroup) {
-      const tagKey = activeTagGroup.toLowerCase();
+      const tagKey = tagAttrKey(activeTagGroup);
       const metaValue = node.tagMetadata[tagKey];
       if (metaValue) {
         nodeG.attr(`data-tag-${tagKey}`, metaValue.toLowerCase());
@@ -781,7 +782,7 @@ export function renderOrg(
       const computedLayout = legendHandle.getLayout();
       if (computedLayout.activeCapsule?.addonX != null) {
         const capsule = computedLayout.activeCapsule;
-        const groupKey = capsule.groupName.toLowerCase();
+        const groupKey = tagAttrKey(capsule.groupName);
         const isHidden = hiddenAttributes?.has(groupKey) ?? false;
 
         // Find the rendered active group <g> and append eye icon

package/src/pert/parser.ts

@@ -36,6 +36,7 @@ import {
   finalizeAutoTagColors,
   AUTO_TAG_COLOR_SENTINEL,
   type TagGroup,
+  tagAttrKey,
 } from '../utils/tag-groups';
 import type { Writable } from '../utils/brand';
 import type { Duration, DurationUnit } from '../gantt/types';
@@ -695,12 +696,12 @@ export function parsePert(
         if (tagBlockMatch.alias) {
           metaAliasMap.set(
             tagBlockMatch.alias.toLowerCase(),
-            tagBlockMatch.name.toLowerCase()
+            tagAttrKey(tagBlockMatch.name)
           );
         }
         metaAliasMap.set(
           normalizeName(tagBlockMatch.name),
-          tagBlockMatch.name.toLowerCase()
+          tagAttrKey(tagBlockMatch.name)
         );
         tagGroups.push(currentTagGroup);
         // Inline values (e.g. `tag Priority as p Low green, High red`).

package/src/sequence/renderer.ts

@@ -2,9 +2,15 @@
 // Sequence Diagram SVG Renderer
 // ============================================================
 
+import { tagAttrKey } from '../utils/tag-groups';
 import * as d3Selection from 'd3-selection';
 import type { PaletteColors } from '../palettes';
-import { contrastText, mix, shapeFill, themeBaseBg } from '../palettes/color-utils';
+import {
+  contrastText,
+  mix,
+  shapeFill,
+  themeBaseBg,
+} from '../palettes/color-utils';
 import {
   parseInlineMarkdown,
   truncateBareUrl,
@@ -1062,7 +1068,7 @@ export function renderSequenceDiagram(
   }
   const getTagColor = (value: string | undefined): string | undefined =>
     value ? tagValueToColor.get(value.toLowerCase()) : undefined;
-  const tagKey = activeTagGroup?.toLowerCase();
+  const tagKey = activeTagGroup ? tagAttrKey(activeTagGroup) : undefined;
 
   // Build hidden message set for collapse support
   const hiddenMsgIndices = new Set<number>();
@@ -2008,11 +2014,7 @@ export function renderSequenceDiagram(
     const groupTagValue = tagKey && group.metadata?.[tagKey];
     const groupTagColor = getTagColor(groupTagValue || undefined);
     const fillColor = groupTagColor
-      ? mix(
-          groupTagColor,
-          themeBaseBg(palette, isDark),
-          isDark ? 15 : 20
-        )
+      ? mix(groupTagColor, themeBaseBg(palette, isDark), isDark ? 15 : 20)
       : isDark
         ? palette.surface
         : palette.bg;
@@ -2137,11 +2139,7 @@ export function renderSequenceDiagram(
 
       // Overlay a taller rect to replace the standard participant box
       const pFill = effectiveTagColor
-        ? mix(
-            effectiveTagColor,
-            themeBaseBg(palette, isDark),
-            isDark ? 30 : 40
-          )
+        ? mix(effectiveTagColor, themeBaseBg(palette, isDark), isDark ? 30 : 40)
         : isDark
           ? mix(palette.overlay, palette.surface, 50)
           : mix(palette.bg, palette.surface, 50);

package/src/sequence/tag-resolution.ts

@@ -5,6 +5,7 @@
 // Resolves effective tag values for participants and messages
 // using the priority chain: explicit > group > receiver-inherit > default > neutral
 
+import { tagAttrKey } from '../utils/tag-groups';
 import type {
   ParsedSequenceDgmo,
   SequenceParticipant,
@@ -116,7 +117,7 @@ export function resolveSequenceTags(
     return result;
   }
 
-  const groupKey = group.name.toLowerCase();
+  const groupKey = tagAttrKey(group.name);
 
   // Clone participant metadata (don't mutate parsed data)
   const participantMeta = new Map<string, Record<string, string>>();

package/src/sitemap/layout.ts

@@ -2,6 +2,7 @@
 // Sitemap Diagram Layout Engine (Dagre flat graph)
 // ============================================================
 
+import { tagAttrKey } from '../utils/tag-groups';
 import dagre from '@dagrejs/dagre';
 import type { Writable } from '../utils/brand';
 import type { ParsedSitemap, SitemapNode } from './types';
@@ -232,7 +233,7 @@ function computeLegendGroups(
   for (const group of tagGroups) {
     if (group.entries.length === 0) continue;
 
-    const usedValues = usedValuesByGroup?.get(group.name.toLowerCase());
+    const usedValues = usedValuesByGroup?.get(tagAttrKey(group.name));
     const visibleEntries = usedValues
       ? group.entries.filter((e) => usedValues.has(e.value.toLowerCase()))
       : group.entries;
@@ -866,7 +867,7 @@ export function layoutSitemap(
   // Collect used tag values
   const usedValuesByGroup = new Map<string, Set<string>>();
   for (const group of parsed.tagGroups) {
-    const key = group.name.toLowerCase();
+    const key = tagAttrKey(group.name);
     const used = new Set<string>();
     const walk = (node: SitemapNode) => {
       if (!node.isContainer && node.metadata[key]) {

package/src/sitemap/parser.ts

@@ -29,6 +29,7 @@ import {
   stripDefaultModifier,
   finalizeAutoTagColors,
   AUTO_TAG_COLOR_SENTINEL,
+  tagAttrKey,
 } from '../utils/tag-groups';
 import {
   measureIndent,
@@ -273,12 +274,12 @@ export function parseSitemap(
       if (tagBlockMatch.alias) {
         metaAliasMap.set(
           normalizeName(tagBlockMatch.alias),
-          tagBlockMatch.name.toLowerCase()
+          tagAttrKey(tagBlockMatch.name)
         );
       }
       metaAliasMap.set(
         normalizeName(tagBlockMatch.name),
-        tagBlockMatch.name.toLowerCase()
+        tagAttrKey(tagBlockMatch.name)
       );
       result.tagGroups.push(newTagGroup);
       continue;
@@ -501,6 +502,16 @@ export function parseSitemap(
         }
       }
 
+      // §12: reject sub-pages nested under a page inside a container.
+      const enclosingContainer = nestedPageInsideContainer(indent, indentStack);
+      if (enclosingContainer) {
+        pushError(
+          lineNumber,
+          `Pages inside container '[${enclosingContainer}]' cannot have indented sub-pages. Containers hold a flat list of pages.`
+        );
+        continue;
+      }
+
       // Node label — possibly with pipe-delimited metadata
       const node = parseNodeLabel(
         trimmed,
@@ -702,6 +713,29 @@ function attachNode(
   indentStack.push({ node, indent });
 }
 
+/**
+ * §12: containers hold a flat list of pages — a page inside a `[Container]`
+ * may not have indented sub-pages. Returns the enclosing container's label
+ * when attaching a page at `indent` would nest it under a page that itself
+ * lives inside a container; otherwise null. Non-destructive (mirrors
+ * `attachNode`'s pop logic without mutating the stack).
+ */
+function nestedPageInsideContainer(
+  indent: number,
+  indentStack: { node: Writable<SitemapNode>; indent: number }[]
+): string | null {
+  let idx = indentStack.length - 1;
+  while (idx >= 0 && indentStack[idx]!.indent >= indent) idx--;
+  if (idx < 0) return null;
+  // Immediate parent. A container parent → flat member, allowed.
+  if (indentStack[idx]!.node.isContainer) return null;
+  // Parent is a page; flag only when an ancestor is a container.
+  for (let k = idx - 1; k >= 0; k--) {
+    if (indentStack[k]!.node.isContainer) return indentStack[k]!.node.label;
+  }
+  return null;
+}
+
 function findParentNode(
   indent: number,
   indentStack: { node: Writable<SitemapNode>; indent: number }[]

package/src/sitemap/renderer.ts

@@ -2,11 +2,17 @@
 // Sitemap Diagram SVG Renderer
 // ============================================================
 
+import { tagAttrKey } from '../utils/tag-groups';
 import * as d3Selection from 'd3-selection';
 import * as d3Shape from 'd3-shape';
 import { FONT_FAMILY } from '../fonts';
 import type { PaletteColors } from '../palettes';
-import { contrastText, mix, shapeFill, themeBaseBg } from '../palettes/color-utils';
+import {
+  contrastText,
+  mix,
+  shapeFill,
+  themeBaseBg,
+} from '../palettes/color-utils';
 import type { ParsedSitemap } from './types';
 import type { SitemapLayoutResult, SitemapLegendGroup } from './layout';
 import { renderInlineText } from '../utils/inline-markdown';
@@ -284,10 +290,10 @@ export function renderSitemap(
   // tagColors: "groupkey:valueLower" → hex color
   const tagColors = new Map<string, string>();
   for (const group of parsed.tagGroups) {
-    displayNames.set(group.name.toLowerCase(), group.name);
+    displayNames.set(tagAttrKey(group.name), group.name);
     for (const entry of group.entries) {
       tagColors.set(
-        `${group.name.toLowerCase()}:${entry.value.toLowerCase()}`,
+        `${tagAttrKey(group.name)}:${entry.value.toLowerCase()}`,
         entry.color
       );
     }
@@ -317,7 +323,7 @@ export function renderSitemap(
 
     // Tag metadata for legend hover dimming
     if (activeTagGroup) {
-      const tagKey = activeTagGroup.toLowerCase();
+      const tagKey = tagAttrKey(activeTagGroup);
       const tagVal = c.tagMetadata[tagKey];
       if (tagVal) cG.attr(`data-tag-${tagKey}`, tagVal.toLowerCase());
     }
@@ -486,7 +492,7 @@ export function renderSitemap(
 
     // Tag metadata for legend hover dimming
     if (activeTagGroup) {
-      const tagKey = activeTagGroup.toLowerCase();
+      const tagKey = tagAttrKey(activeTagGroup);
       const tagVal = node.tagMetadata[tagKey];
       if (tagVal) nodeG.attr(`data-tag-${tagKey}`, tagVal.toLowerCase());
     }
@@ -721,7 +727,7 @@ function renderLegend(
     const computedLayout = legendHandle.getLayout();
     if (computedLayout.activeCapsule?.addonX != null) {
       const capsule = computedLayout.activeCapsule;
-      const groupKey = capsule.groupName.toLowerCase();
+      const groupKey = tagAttrKey(capsule.groupName);
       const isHidden = hiddenAttributes?.has(groupKey) ?? false;
 
       const activeGroupEl = parent.select(`[data-legend-group="${groupKey}"]`);

package/src/timeline/renderer.ts

@@ -2,6 +2,7 @@
 // Timeline renderer — Story 109.2 (arch-review). Extracted from d3.ts.
 // ============================================================
 
+import { tagAttrKey } from '../utils/tag-groups';
 import * as d3Scale from 'd3-scale';
 import * as d3Selection from 'd3-selection';
 import { FONT_FAMILY } from '../fonts';
@@ -820,7 +821,7 @@ function setupTimeline(
   let tagLanes: Lane[] | null = null;
 
   if (resolvedSwimlaneTG) {
-    const tagKey = resolvedSwimlaneTG.toLowerCase();
+    const tagKey = tagAttrKey(resolvedSwimlaneTG);
     const tagGroup = parsed.timelineTagGroups.find(
       (g) => g.name.toLowerCase() === tagKey
     );
@@ -1322,7 +1323,7 @@ function renderTimelineTagLegendOverlay(
               onTagStateChange?.(currentActiveGroup, currentSwimlaneGroup);
             },
             onEntryHover: (groupName, entryValue) => {
-              const tagKey = groupName.toLowerCase();
+              const tagKey = tagAttrKey(groupName);
               if (entryValue) {
                 const tagVal = entryValue.toLowerCase();
                 fadeToTagValue(mainG, tagKey, tagVal);
@@ -1349,7 +1350,7 @@ function renderTimelineTagLegendOverlay(
               }
             },
             onGroupRendered: (groupName, groupEl, isActive) => {
-              const groupKey = groupName.toLowerCase();
+              const groupKey = tagAttrKey(groupName);
               groupEl.attr('data-tag-group', groupKey);
               if (isActive && !viewMode) {
                 const isSwimActive =

package/src/utils/legend-d3.ts

@@ -3,6 +3,7 @@
 // Thin adapter: layout engine → D3 DOM
 // ============================================================
 
+import { tagAttrKey } from './tag-groups';
 import {
   LEGEND_HEIGHT,
   LEGEND_PILL_FONT_SIZE,
@@ -164,7 +165,7 @@ function renderCapsule(
   const g = parent
     .append('g')
     .attr('transform', `translate(${capsule.x},${capsule.y})`)
-    .attr('data-legend-group', capsule.groupName.toLowerCase())
+    .attr('data-legend-group', tagAttrKey(capsule.groupName))
     .style('cursor', 'pointer');
 
   // Outer capsule background
@@ -211,7 +212,7 @@ function renderCapsule(
   // Continuous ramp (choropleth group): min | gradient | max, in place of dots.
   if (capsule.gradient) {
     const gr = capsule.gradient;
-    const gradId = `dgmo-legend-ramp-${capsule.groupName.toLowerCase().replace(/[^a-z0-9]+/g, '-')}`;
+    const gradId = `dgmo-legend-ramp-${tagAttrKey(capsule.groupName).replace(/[^a-z0-9]+/g, '-')}`;
     const def = g.append('defs').append('linearGradient').attr('id', gradId);
     // Sample the SAME ramp the fills use (direct = 2 endpoints; diverging =
     // stops through the neutral midpoint), so the legend matches the basemap.
@@ -318,7 +319,7 @@ function renderPill(
   const g = parent
     .append('g')
     .attr('transform', `translate(${pill.x},${pill.y})`)
-    .attr('data-legend-group', pill.groupName.toLowerCase())
+    .attr('data-legend-group', tagAttrKey(pill.groupName))
     .style('cursor', 'pointer');
 
   g.append('rect')

package/src/utils/legend-svg.ts

@@ -12,6 +12,7 @@
 // (not dominant-baseline) so resvg renders it correctly in PNG export.
 // ============================================================
 
+import { tagAttrKey } from './tag-groups';
 import type {
   LegendConfig,
   LegendState,
@@ -99,7 +100,7 @@ function emitCapsule(
     );
   }
 
-  return `<g transform="translate(${capsule.x},${capsule.y})" data-legend-group="${esc(capsule.groupName.toLowerCase())}" style="cursor:pointer">${inner.join('')}</g>`;
+  return `<g transform="translate(${capsule.x},${capsule.y})" data-legend-group="${esc(tagAttrKey(capsule.groupName))}" style="cursor:pointer">${inner.join('')}</g>`;
 }
 
 /** Collapsed group pill (no active group) → SVG string. */
@@ -109,7 +110,7 @@ function emitPill(
   groupBg: string
 ): string {
   return (
-    `<g transform="translate(${pill.x},${pill.y})" data-legend-group="${esc(pill.groupName.toLowerCase())}" style="cursor:pointer">` +
+    `<g transform="translate(${pill.x},${pill.y})" data-legend-group="${esc(tagAttrKey(pill.groupName))}" style="cursor:pointer">` +
     `<rect width="${pill.width}" height="${pill.height}" rx="${pill.height / 2}" fill="${esc(groupBg)}"/>` +
     `<text x="${pill.width / 2}" y="${pill.height / 2 + LEGEND_PILL_FONT_SIZE / 2 - 2}" font-size="${LEGEND_PILL_FONT_SIZE}" font-weight="500" fill="${esc(palette.textMuted)}" text-anchor="middle" font-family="${esc(FONT_FAMILY)}">${esc(pill.groupName)}</text>` +
     `</g>`

package/src/utils/tag-groups.ts

@@ -39,6 +39,23 @@ export interface TagGroup {
   readonly lineNumber: number;
 }
 
+/**
+ * DOM-safe key for a tag group — used wherever the group name becomes a
+ * `data-tag-*` attribute suffix, an entity metadata key, or an `active-tag`
+ * match target. For a single-identifier name (the only form the parser used to
+ * accept) this is exactly `name.toLowerCase()`, so swapping it in for existing
+ * diagrams is byte-identical. A quoted multi-word name (`tag "Trust Zone" as tz`)
+ * slugs to a hyphenated identifier (`trust-zone`) so it never produces an
+ * invalid DOM attribute name; the original `name` is kept for the legend label.
+ */
+export function tagAttrKey(name: string): string {
+  return name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9_-]+/g, '-')
+    .replace(/^-+|-+$/g, '');
+}
+
 /** Result of matching a tag block heading */
 interface TagBlockMatch {
   name: string;
@@ -450,12 +467,12 @@ export function resolveTagColor(
   if (!activeGroupName) return undefined;
 
   const group = tagGroups.find(
-    (g) => g.name.toLowerCase() === activeGroupName.toLowerCase()
+    (g) => tagAttrKey(g.name) === tagAttrKey(activeGroupName)
   );
   if (!group) return undefined;
 
   const metaValue =
-    metadata[group.name.toLowerCase()] ??
+    metadata[tagAttrKey(group.name)] ??
     (isContainer ? undefined : group.defaultValue);
   if (!metaValue) return '#999999';
 
@@ -489,7 +506,7 @@ export function validateTagValues(
   if (tagGroups.length === 0) return;
 
   const groupMap = new Map<string, TagGroup>();
-  for (const g of tagGroups) groupMap.set(g.name.toLowerCase(), g);
+  for (const g of tagGroups) groupMap.set(tagAttrKey(g.name), g);
 
   for (const entity of entities) {
     for (const [key, value] of Object.entries(entity.metadata)) {
@@ -557,10 +574,14 @@ export function validateTagGroupNames(
         `'none' is a reserved keyword and cannot be used as a tag group name`
       );
     }
-    if (!VALID_TAG_IDENT_RE.test(group.name)) {
+    // A single-identifier name is valid as-is; a multi-word name is valid when
+    // quoted (`tag "Trust Zone" as tz`) — it slugs to a DOM-safe key while the
+    // original text stays the legend label. Reject only names whose slug is
+    // not a usable identifier (e.g. all-punctuation, or leading digit).
+    if (!VALID_TAG_IDENT_RE.test(tagAttrKey(group.name))) {
       report(
         group.lineNumber,
-        `Tag group name "${group.name}" contains invalid characters — use a single identifier (letters, digits, underscore, hyphen)`
+        `Tag group name "${group.name}" can't form a valid key — use letters, digits, underscore, or hyphen, and quote a multi-word name (e.g. tag "Trust Zone" as tz)`
       );
     }
     if (group.alias != null && !VALID_TAG_IDENT_RE.test(group.alias)) {
@@ -591,7 +612,7 @@ export function validateTagGroupNames(
 export function cascadeTagMetadata<
   T extends { metadata: Record<string, string>; children: readonly T[] },
 >(roots: readonly T[], tagGroups: ReadonlyArray<{ name: string }>): void {
-  const keys = tagGroups.map((g) => g.name.toLowerCase());
+  const keys = tagGroups.map((g) => tagAttrKey(g.name));
   if (keys.length === 0) return;
 
   const walk = (node: T, inherited: Record<string, string>): void => {
@@ -629,7 +650,7 @@ export function injectDefaultTagMetadata(
   for (const group of tagGroups) {
     if (group.defaultValue) {
       defaults.push({
-        key: group.name.toLowerCase(),
+        key: tagAttrKey(group.name),
         value: group.defaultValue,
       });
     }

package/src/visualizations/parse.ts

@@ -36,6 +36,7 @@ import {
   stripDefaultModifier,
   validateTagGroupNames,
   validateTagValues,
+  tagAttrKey,
 } from '../utils/tag-groups';
 import type { TagGroup } from '../utils/tag-groups';
 import type { Writable } from '../utils/brand';
@@ -1364,7 +1365,7 @@ function parseVisualizationFull(
       );
       for (const group of result.timelineTagGroups) {
         if (!group.defaultValue) continue;
-        const key = group.name.toLowerCase();
+        const key = tagAttrKey(group.name);
         for (const event of result.timelineEvents) {
           if (!event.metadata[key]) {
             event.metadata[key] = group.defaultValue;